Rental Frontend — Slices 3, 4, and 5 (Panel)

Summary

Three sequential SolidStart panel changes — rental-slice3-panel, rental-slice4-panel, rental-slice5-panel — build the twelve rental screens that already have backend support but no frontend code. Together they take the platform from "a renter can ask to view a property" through offers, e-signature, rent ledger, payment proof, and a finalized move-in report. The design is settled; release is blocked on four missing backend capabilities and three backend defects.

• Area frontend/solidstart/apps/panel
• Delivery Three OpenSpec changes, merged in order 3 → 4 → 5
• Surface Landlord /owner/* plus renter /tenant/*, one responsive panel
• Reference 14-screen demo — landlord 01–09, tenant 10–14
• Reviewed 2026-09-05 grill session, twelve settled decisions
• Release state Blocked — 4 backend capabilities, 3 backend defects

What exists today

Backend slices 1–4 are merged on main; slice 5 is complete on the still-open PR #109 branch. Twelve of the fourteen demo screens have no frontend code at all.

Scope

Core decisions

Demo versus backend, resolved

The demo was drawn before the backend settled. Seven conflicts are resolved in the backend's favour, and anyone comparing the built product against the mockup will find these differences by design rather than by regression.

Slice 3 — offers and agreements

Demo screens 05, 06, 12.

/owner and /owner/:id are untouched slice 1 routes.

flowchart LR
    V["Confirmed viewing"] --> O["POST /requests/:id/offers"]
    O --> P["pending"]
    P -->|counter| C["countered"]
    C -->|reoffer| P
    P -->|decline| D["declined"]
    P -->|withdraw| W["withdrawn"]
    P -->|accept| A["accepted"]
    A --> AG["Agreement: awaiting_signatures"]
    AG -->|both parties sign| CO["completed"]
    AG -->|void with reason| VD["voided"]
    CO --> SW["Competing offers closed"]
    

Offer queue

Fed by GET /me/offers, a backend prerequisite. The endpoint is party-scoped and role-agnostic like /me/agreements and /me/tenancies: the owner queue filters landlord_user_id == me, the tenant view filters tenant_user_id == me, and that filtering is presentation, not authorization. Ordering is oldest first and deterministic. Status filtering is server-side so live and history are separate reads. Counts are never derived from a truncated page.

Offer terms comparison

An absent or unspecified asking value renders as "Not specified", never as a zero that would imply a negotiated term. The comparison context is the current listing, not a historical negotiation snapshot; the screen never fabricates a past asking value from a present one. Offers have five statuses and five actions mapping 1:1 to endpoints, and no expiry, so there is no countdown.

Two gates before an offer can be created

• ErrViewingNotConfirmed The offer form is only reachable from a confirmed viewing 1
• ErrMissingPartyDetails Full name and NRIC must be collected first, via PUT /me/contact 2

Sign screen

Money terms first, legal text second, then the attestation. The frozen party name and address render as an agreement summary. full_name and nric are typed into blank attestation inputs. address_line is displayed and submitted read-only from the matching party snapshot. agree is an explicit unchecked checkbox. The raw NRIC is never prefilled — it is masked everywhere it appears — and a later /me/contact address is never used, because the snapshot is frozen at issue and a newer address would fail the comparison with no in-UI remedy.

Name normalization

Server-side: uppercased and space-collapsed

NRIC normalization

Server-side: reduced to digits

Address normalization

Server-side: whitespace-collapsed but case-sensitive

Mismatch transport

422 with a flat message — the existing transport, unchanged

The panel shows a 422 failure inline at the attestation form with the server's explanation, and attaches it to a specific field only when the field is unambiguously identified. It does not treat every 422 as an NRIC error and does not parse arbitrary error prose as though it were a stable structured API. There is no blanket promise of per-field errors and no new backend error-shape endpoint.

If the frozen details are wrong, the screen explains that editing the contact will not change this agreement. Either party may void while awaiting_signatures, with a reason; the user then corrects their own contact and a fresh offer produces a fresh agreement. There is no reissue endpoint and none is invented.

Agreement detail and signatures

Three agreement states only: awaiting_signatures, completed, voided. Who has signed is answered by a sanitized signatures[] array embedded on GET /agreements/:id — signer_role, user_id, signed_at, and the document hash, with no raw NRIC, IP address, or user agent. Signer names come from the snapshot (terms.landlord.full_name, terms.tenant.full_name) joined on signer_role.

Who signed and when is the primary information. The document hash is secondary evidence, shown in an expandable details area if shown at all. There is no mismatch state and no unexplained truncated hash badge. After signing or voiding, the screen refetches the detail rather than inferring state from a mutation response that carries no signature summary.

Slice 4 — ledger and payments

Demo screens 07, 08, 10, 13. The largest of the three changes.

The slice 2 /tenant root and /tenant/requests are preserved. Every tenancy-scoped route names the tenancy in the path, and every fetched record is verified to belong to it. Zero tenancies shows a clear empty state linking to viewings and agreements. Several tenancies stay as separate cards; the UI never auto-picks one.

Two money units are on the wire, not one

Conversion happens exactly once, server-side, when the charge schedule is generated. The panel preserves wire units and never converts on ingest or on a mutation round trip. Two explicit formatters, formatRinggit and formatSen, with unit-labelled API types and field names. Regression examples: formatRinggit(2800) and formatSen(280000) must both render RM 2,800.00. Branded money types are deliberately not used — the slice 1 API is unbranded and consistency is worth more here.

Selected-charge sums and payment inputs stay integer sen. Decimal RM input is parsed explicitly, without floating-point rounding drift. Deposit months (security_deposit_months, utility_deposit_months, advance_rent_months) are decimal multipliers displayed as months, not as currency, at the server contract's precision and defaults. term_months stays an integer. The panel adds no deposit rule stricter than the backend's.

Ledger

GET /tenancies/:id/charges returns the combined TenancyLedger: tenancy, charges, records, and allocations. Charges have three types (security_deposit, utility_deposit, rent) and three statuses (open, paid, cancelled). The whole fixed-term schedule is generated once at establishment, so the landlord sees the entire tenancy on one page.

A landlord can cancel a charge with a reason, reopen it with a reason, and generate a late notice (POST /charges/:id/late-notice, streamed from /late-notices/:id). Cancellation stops reminders; reopening does not resurrect them.

Tenancy list labelling. GET /me/tenancies returns bare tenancies with property_id but no address. The address is obtained by joining the frozen property snapshots in GET /me/agreements to GET /me/tenancies on agreement_id — two collection reads, not one read per row. This applies to both the owner and renter lists. Next-payment amount and date live on tenancy detail, fetched from its ledger; the lists do not make one ledger call per card to decorate themselves.

Payment review

Five record statuses — draft, pending_review, confirmed, rejected, reversed — presented separately. The demo's "every reason to hesitate" is genuinely backed by three separate signals:

• ai_agreement agrees | differs | fields_unreadable | not_applicable headline badge 4
• unreadable_fields Names each field the model could not read, rather than inferring it n
• duplicate_signals[] {signal_type, detail} — deterministic duplicate detection, rendered as a list n

Confirm and reject act on the record as a whole. A confirmed record can be reversed with a reason, never deleted. Terminal states are conflict-safe and repeat-safe, so a stale tab that double-confirms gets a clean conflict message rather than an error page. Only a landlord decision marks a charge paid — the AI never blocks or approves.

Tenant pay wizard and the consent handshake

The wizard is server-backed from step 1, because proof upload requires an existing record.

1. Step 1 — create a validated draft

   The panel mints one UUIDv7 before the create call and keeps it for the life of that logical operation. Only the draft and tenancy identifiers live in route state, for reload recovery; the server ledger owns saved values and the proof. On an uncertain create or submit outcome, the panel GETs the same identifier before attempting another mutation, and never mints a fresh identifier merely because a response was lost.

2. Step 2 — optionally upload a JPEG or PNG proof

   Sent with the current consent choice. Selected charges must be whole and open, and their sum must equal the amount exactly; there are no partial charges. A stale-charge conflict is handled by refreshing and reselecting.

3. Step 3 — save final values via PUT, then submit explicitly

   Submission is a distinct user action, never implied by saving.

flowchart TD
    S["Enter wizard"] --> L["List all own drafts for this tenancy"]
    L -->|Resume| R["Existing draft"]
    L -->|Discard| DEL["DELETE draft"]
    L -->|New| M["Mint one UUIDv7"]
    M --> C["POST create draft"]
    R --> AV
    C --> AV{"GET /ai/availability"}
    AV -->|available| CD["Consent disclosure shown before any image is sent"]
    AV -->|unavailable| MAN["Manual run: AI not used"]
    CD -->|accept| UPY["Upload proof, echo provider + ai_config_version"]
    CD -->|decline| MAN
    MAN --> UPN["Upload proof, no consent fields"]
    UPY --> F["PUT final values"]
    UPN --> F
    F --> SUB["Submit to pending_review"]
    

If AI is unavailable, the tenant declines, the configuration is stale, or extraction fails, the wizard runs fully manual with a neutral "AI not used" message. The backend treats that as not_applicable, not an error. Images are never silently resubmitted to a newly configured provider.

Dashboard

Fed by GET /landlord/dashboard-summary, which returns aggregates and counts with a server as_of timestamp and without N ledger reads.

Slice 5 — move-in handover

Demo screens 09 and 14. Blocked on PR #109 landing. The spec is written against the branch; the build waits for the merge. The branch's drift from main is not recorded here because any such figure goes stale.

Routes: /owner/tenancies/:id/handover (builder) and /tenant/handover/:id (review). Neither adds a top-level nav item.

stateDiagram-v2
    [*] --> draft
    draft --> tenant_review: SubmitBaseline passes both gates
    tenant_review --> finalized: tenant_accepted
    tenant_review --> finalized: deadline_elapsed
    finalized --> [*]
    

Builder

Areas hold entries of four types: condition, inventory, access_device, and meter_reading.

Media: images only, no video. Formats and limits follow the slice 5 contract, with distinct guidance for HEIC. Thumbnails render by default; the original downloads only on an explicit request. Media runs uploading → ready → failed, staged then attached. upload_request_id is stable across retries of the same upload; persisted media is recovered through the report detail; a 410 after staged cleanup requires a fresh upload. low_resolution_warning is informational and never blocks submission.

Two submission gates the builder mirrors

SubmitBaseline enforces ErrAreaRequiresImage and ErrMeterRequiresImage. The builder shows named area and meter completeness with links to the offender, and disables submit while required media are absent or still processing. The mapping matches the code exactly:

The backend still enforces every gate, and a conflict is surfaced inline after a refresh. This mirrors the server predicate early; it does not replace it. After submit the baseline is immutable, and review responses are append-only.

AI drafts; users author

Consent is per report and per party and versioned per uploader (POST / GET / DELETE /handover-reports/:id/ai-consent), so the demo's AI on/off toggle maps cleanly onto grant and withdraw. POST /handover-media/:id/analyze returns a suggestion with status succeeded, unavailable, failed, or invalid — four states the UI handles, not just success. Suggested fields arrive as separate nullable records and nothing is copied into the report until the user applies or edits it. ai_assisted marks applied text and stays set after editing, which is exactly the demo's "AI draft, edited by you · original kept". Withdrawal stops future calls and deletes nothing. Handover owns its withdraw action; payments have none.

Thread rules and acceptance

flowchart LR
    E["Entry"] -->|dispute_entry| T["Thread: open"]
    RP["Report"] -->|report_omission| T
    T -->|reply| T
    T -->|resolve, not self| RS["resolved"]
    T -->|withdraw| WD["withdrawn"]
    RS --> ACC["Accept enabled"]
    WD --> ACC
    T -.->|blocks| ACC
    

The server ships the reduction: detail.threads[] carries thread_id, target_type, target_id, status, opened_by, last_actor_id, last_action, and events[]. The panel derives button availability only from those shipped fields — whose turn it is from last_actor_id plus the no-self-resolve rule, and can-accept from "no thread has status open". It renders events[] for display and never re-reduces them.

1. ErrOpenThreadBlocksAcceptance

   Checked first. Resolve the open thread before acceptance is possible.

2. ErrStaleReviewedSnapshot

   A stale 409. The screen shows the refreshed state and requires a new explicit acceptance. Acceptance is never retried automatically.

The two blockers must not share a message. Expired and finalized reports get their own distinct messages. Refresh policy: refetch after a mutation and on window focus. No live-update infrastructure is required.

Cross-cutting

Shared primitives

Money

Two formatters, formatRinggit and formatSen, each unit-tested

Dates

One date and deadline formatter pinned to Asia/Kuala_Lumpur — the finalization sweep runs on the Malaysian date ending, so rendering a deadline in the browser's timezone would show the wrong day to anyone travelling

Status labels

Slice 1's status.ts pattern (STATUS_LABEL / STATUS_VARIANT) extends to each new state machine, including the computed tenancy label

AI consent

One shared component, disclosure only. Payments and handover share the disclosure and the explicit accept-or-decline choice; each feature owns its own endpoint and echo lifecycle. Withdrawal is not part of the shared component — handover owns a separate withdraw action, payments have none

Proxy — verified, nothing to do

src/routes/api/rental/[...path].ts forwards the raw request body and streams the upstream response back, so multipart uploads (proof slips, handover images) and binary downloads (agreement PDFs, late notices) already work. No new proxy route, no new environment variable.

i18n

Testing

Per frontend/AGENTS.md: headless pnpm e2e is the committed Playwright suite and is allowed. Anything exploratory — finding selectors, reproducing a bug, confirming a fix visually — goes through ego lite via /ego-browser. Chrome, --headed, and Playwright MCP are banned. The frontend OpenSpec schema requires a per-task verification method, so every task in tasks.md declares TDD, render-test, e2e, or browser.

Documentation

No change is needed to CONTEXT.md, to any ADR, or to any other spec. The existing glossary terms — Offer, Tenancy Agreement, Tenancy, Issue, Void, Charge Cancellation, Payment Record, Reversal — already cover every concept used here. This review introduced no new domain term and reinterpreted none.

Backend prerequisites

Slice 3 — two read capabilities

Slice 4 — one capability and three blocking defects

Slice 5

PR #109 must land. No other backend item is outstanding for handover.

Delivery order

1. Build rental-slice2-panel

   From its existing spec, to its own acceptance criteria. Prerequisite, not part of this work. Recheck the delivered slice 2 shell when slice 3 starts.

2. Land the slice 3 backend read prerequisites

   GET /me/offers and the sanitized signatures[] projection.

3. rental-slice3-panel

   Dashboard route, nav row, offers, agreements, signing.

4. Land the slice 4 backend prerequisites

   One new capability plus three defect fixes.

5. rental-slice4-panel

   Ledger, payments, tenant tenancies and pay wizard. Nav gains Tenancies and Payments; dashboard tiles ship as their contracts land.

6. Rebase and merge PR #109

   The slice 5 backend branch.

7. rental-slice5-panel

   Handover builder and review.

What this unblocks. With all three merged, the rental platform is usable end to end in one product: a tenant finds a listing, asks to view it, offers terms, signs, pays, and reviews their move-in report; a landlord answers, accepts, countersigns, confirms payment, and files the baseline. The remaining gaps after this are the Astro public marketplace and any move-out handover, neither of which has a frontend change yet.

Risks and trade-offs

Reviewed decision record

Twelve decisions from the 2026-09-05 grill session. Each is settled; none is an open question.

Assumptions

These are stated choices, not derived facts. A reader who disagrees should reopen the relevant decision rather than assume the code proves it.

1. Preserving existing URLs outranks matching the demo's navigation. Landlords already hold /owner and /owner/:id links.
2. "Confirmed this month" measures confirmation activity. Not cashflow, accounting income, or rent earned. It includes deposits and landlord receipts, spans ended tenancies, and can change after a reversal. paid_on was rejected because it can be absent and is user-entered. A conservative product choice, not an accounting definition, and it adds no glossary term.
3. Client-side filtering of role-agnostic /me collections is presentation only. It is never treated as authorization.
4. Frontend gate mirroring contains but does not remediate the backend defects. A direct API caller still reaches the bad state.
5. The sign-screen interaction is a conservative UX choice, not a claim about legal sufficiency under ADR-0059.
6. The current listing is the comparison context for an offer, not a historical negotiation snapshot.
7. Tenancy scheduled/active/ended is a display label only. Not a backend lifecycle and not a permission gate. An ended tenancy may still hold open obligations.