WAP LabsProject atlas

docs/wml-engine/work-items.md

WaveNav Engine Work Items (Execution Board)

Purpose: convert the phase plan into PR-sized implementation tickets for immediate execution.

Status keys:

  • todo
  • in-progress
  • blocked
  • done

Archive:

  • docs/wml-engine/work-items-archive.md

Current Execution Scope

The first usable WML form lane is now landed. Active engine focus should shift back to runtime fidelity and deferred capability closure:

  • deterministic history/context fidelity
  • timer/dialog runtime semantics
  • stable native/wasm parity for active runtime surfaces
  • planning-ready debug boundary contracts before fresh host-boundary migration work

Keep wider Phase B+/C expansion deferred unless it directly serves the active runtime-compliance lane.

Next In Line (Cross-Project Alignment Refresh)

With WML-202 deck/access/card-context closure and the WML-205 engine-boundary taxonomy slice implemented, current aligned engine priorities are:

  1. Preserve WML-201’s completed 76-row SCR evidence projection and its 174/174 direct WML-clause mapping.
  2. Preserve the mapped WML-205 malformed/invalid/unsupported/recoverable load taxonomy, then close its residual exhaustive error-enforcement and host fetch/access failure-atomicity gates.
  3. Close the residual WML-204 field/control validation gate without reopening completed WML-202 evidence.
  4. Preserve the completed WML-202 30/30, WML-203 49/49, and WML-204 23/23 direct-clause slices; WML-202 has no remaining work-item acceptance gate.
  5. Keep D0-01, W1-06, and M1-03 non-preemptive until the upstream WML-2 gate materially changes.

Source of truth for these items:

  • docs/waves/MAINTENANCE_WORK_ITEMS.md

Committed Sprint Alignment (2026-03-04)

Current committed sequence for engine-impacting compliance work:

  1. A5-01 history entry fidelity.
  2. R0-02 inter-card process-order conformance support.
  3. R0-03 history/context fidelity closure support.
  4. W0-06 bytecode verification gates.
  5. Stretch: W1-02 structural verification closure.

Execution plan reference:

  • docs/waves/SPRINT_PLAN_2026-03_MASTER_PRIORITIZED.md (cross-lane canonical priority plan)
  • docs/waves/SPRINT_PLAN_2026-03_BEDROCK_COMPLIANCE.md

Demoability Requirement

For any newly implemented, demoable feature:

  • add a new engine-wasm/examples/source/*.wml fixture, or
  • update an existing shared example that directly exercises the new behavior.

Every completed ticket with host-visible behavior should note which example covers it. Each example metadata block must include:

  • work item and/or spec IDs (work-items, spec-items)
  • brief description and goal
  • testing-ac checklist steps for deterministic manual verification

When behavior is stable enough for automated browser replay, add an optional adjacent *.flow.json companion and validate it with pnpm test:story <work-item-or-spec-id>.

Ticket Template

Use this shape for any new ticket:

  1. ID: stable id (A1-01, A2-02, etc.)
  2. Requirement IDs: links to requirements-matrix.md
  3. Status
  4. Depends On
  5. Files
  6. Build
  7. Tests
  8. Accept

Traceability Rule

  • Every ticket must map its Requirement IDs to Waves requirement IDs using:
    • docs/wml-engine/requirements-matrix.md (“Waves Traceability Mapping”)
    • docs/waves/RUNTIME_MARKUP_SPEC_TRACEABILITY.md
    • docs/waves/WAE_SPEC_TRACEABILITY.md (where applicable)
  • Any contract-impacting ticket must also update:
    • docs/waves/CONTRACT_REQUIREMENTS_MAPPING.md
    • docs/waves/SPEC_TEST_COVERAGE.md

Ticket Lifecycle Guardrail

  • Do not rewrite done tickets to a non-done status during later audits.
  • When spec gaps are discovered in previously completed areas, create additive follow-up tickets that reference the completed ticket in Depends On and notes.

Phase A Implementation Queue

Completed Phase A (A1 through A4) tickets are archived in:

  • docs/wml-engine/work-items-archive.md

Compliance Follow-up Queue (Additive; Do Not Reopen done Tickets)

Completed compliance follow-up ticket A5-02 is archived in:

  • docs/wml-engine/work-items-archive.md

A5-01 History entry fidelity follow-up

  1. Requirement IDs: WML-R-008
  2. Status: done
  3. Depends On: A2-03
  4. Files:
  • engine-wasm/engine/src/lib.rs
  • engine-wasm/engine/src/runtime/*
  • browser/contracts/transport-app.ts
  • browser/frontend/src/session-history.ts
  • browser/frontend/src/app/navigation-state.ts
  • engine-wasm/contracts/wml-engine.ts
  1. Build:
  • Expand history entries from card-index-only behavior to spec-shaped request identity entries (absolute URL, method, post data, request metadata).
  • Preserve deterministic back behavior across in-deck and fetched-deck transitions.
  1. Tests:
  • Add history fixture tests for repeated URL entries, method-aware back behavior, and deterministic restore snapshots.
  1. Accept:
  • Back behavior is deterministic and history entries preserve required request identity fields.
  1. Notes:
  • Compliance delta for A2-03 without changing its completed status.
  • Evidence:
    • Engine in-deck history/back semantics remain covered in engine-wasm/engine/src/engine_tests/actions_timers.rs (navigate_back_restores_previous_card, navigate_back_returns_false_when_history_empty) and engine-wasm/engine/src/engine_tests/traces_public_api.rs (m1_02_handle_key_render_and_navigate_back_public_api_flow).
    • Browser request-shaped host history coverage landed in browser/frontend/src/session-history.test.ts, browser/frontend/src/app/navigation-state.load.test.ts, and browser/frontend/src/app/navigation-state.history.test.ts, including repeated-URL entries, method-aware/post-aware replay, and deterministic restore/fallback behavior.

A5-03 WML timer lifecycle runtime follow-up

  1. Requirement IDs: WML-R-014
  2. Status: in-progress
  3. Depends On: A5-02
  4. Files:
  • engine-wasm/engine/src/runtime/events.rs
  • engine-wasm/engine/src/lib.rs
  • engine-wasm/engine/tests/fixtures/*
  1. Build:
  • Implement <timer> lifecycle semantics (card-entry start, card-exit stop, refresh resume, ontimer dispatch, invalid timeout ignore).
  • Keep timer ownership in runtime semantics; host only supplies timing capability plumbing.
  1. Tests:
  • Deterministic simulated clock tests for start/stop/resume/expire.
  1. Accept:
  • Timer behavior is deterministic and card-scoped under navigation and refresh paths.
  1. Notes:
  • Distinct from WaveScript timer hostcalls tracked in docs/waves/WORK_ITEMS.md.

A5-04 Minimal WML text-input interaction baseline

  1. Requirement IDs: WML-R-019
  2. Status: done
  3. Depends On: A5-02, T0-30
  4. Files:
  • engine-wasm/engine/src/parser/wml_parser/*
  • engine-wasm/engine/src/runtime/*
  • engine-wasm/engine/src/layout/*
  • engine-wasm/engine/tests/fixtures/*
  • engine-wasm/contracts/wml-engine.ts
  1. Build:
  • parse and retain text-input field metadata as runtime-owned controls instead of submit-only metadata
  • implement deterministic focus, enter-edit, commit, and cancel behavior for text inputs in the constrained viewport
  • render active field values and focus state through the existing engine output contract
  • keep field state authoritative in the engine so browser glue remains input/event plumbing only
  1. Tests:
  • fixture matrix for text-input focus traversal, edit commit, edit cancel, and variable updates
  • native/wasm parity checks for rendered field state and submit metadata
  1. Accept:
  • login/register-style text fields are editable in the viewport and their committed values survive re-render and submit preparation
  1. Notes:
  • first ticket is intentionally text-input only; defer select controls and mask-edge semantics
  • Evidence:
    • engine input edit lifecycle + maxlength + postfield payload feed tests in engine-wasm/engine/src/engine_tests/navigation_metadata.rs and engine-wasm/engine/src/engine_tests/actions_timers.rs
    • host command/render integration tests in browser/src-tauri/src/tests/tauri_commands.rs

A5-05 WML select/option interaction baseline

  1. Requirement IDs: WML-R-019
  2. Status: done
  3. Depends On: A5-04
  4. Files:
  • engine-wasm/engine/src/parser/wml_parser/*
  • engine-wasm/engine/src/runtime/*
  • engine-wasm/engine/src/layout/*
  • engine-wasm/engine/tests/fixtures/*
  1. Build:
  • add runtime representations for select and option
  • implement deterministic focus, choice cycling, commit, and cancel behavior
  • preserve option ordering and selected state in engine-owned form state
  1. Tests:
  • fixtures for default-selected option, user choice changes, cancel behavior, and rendered selection state
  1. Accept:
  • select controls can be navigated and updated without host-owned form state
  1. Notes:
  • keep baseline scope to single-select behavior unless live decks force a broader cut
  • Landed in #108 with deterministic select edit lifecycle, render integration, host command coverage, and local example fixtures.

A5-06 Form-state submit integration hardening

  1. Requirement IDs: WML-R-019
  2. Status: done
  3. Depends On: A5-04, A5-05, T0-30
  4. Files:
  • engine-wasm/engine/src/runtime/*
  • engine-wasm/engine/src/lib.rs
  • engine-wasm/contracts/wml-engine.ts
  • engine-wasm/engine/tests/fixtures/*
  1. Build:
  • make engine-owned field state the single source of truth for postfield resolution at submit time
  • harden substitution timing, empty/default field behavior, and deterministic postfield ordering after interactive edits
  1. Tests:
  • fixtures proving edited values, untouched defaults, and empty values yield deterministic submit payloads
  • parity tests for native/wasm request metadata snapshots
  1. Accept:
  • interactive viewport edits are reflected in the exact submit metadata emitted by the engine contract
  1. Notes:
  • this closes the gap between editable controls and the already-landed native transport POST path
  • Closed for the active MVP lane via native/browser submit coverage and deterministic engine-owned field-state resolution across the merged form/browser hardening series.

B5-01 Input mask and commit semantics conformance follow-up

  1. Requirement IDs: WML-R-019
  2. Status: in-progress
  3. Depends On: A5-02
  4. Files:
  • engine-wasm/engine/src/parser/wml_parser/*
  • engine-wasm/engine/src/runtime/*
  • engine-wasm/engine/tests/fixtures/*
  1. Build:
  • Add minimum-conformance input object behavior: mask validation at commit, invalid commit rejection without variable mutation, deterministic initialization order.
  1. Tests:
  • Input mask fixture matrix including invalid-mask-ignore and empty-string commit rules.
  1. Accept:
  • Input/form commit flow is deterministic and spec-aligned for baseline text input semantics.
  1. Notes:
  • Additive follow-up over Phase C planning scope to close compliance-critical gaps earlier.
  • Basic Latin mask codes, escaped literals, invalid-mask fallback, emptyok precedence, rejection atomicity, maxlength, password display, and name/value initialization are implemented with native/WASM parity and Waves-browser story evidence. Input value vdata defaults now evaluate in document order. General vdata validation/conversion beyond input defaults and language-aware non-Basic-Latin input repertoires remain before this item can close; the mandatory Basic Latin floor is directly tested.

B5-02 Inline flow layout conformance follow-up

  1. Requirement IDs: WML-R-021, WML-R-023
  2. Status: todo
  3. Depends On: A3-01, A3-02, M1-07
  4. Files:
  • engine-wasm/engine/src/layout/flow_layout.rs
  • engine-wasm/engine/src/parser/wml_parser/*
  • engine-wasm/engine/src/runtime/node.rs
  • engine-wasm/engine/tests/fixtures/*
  1. Build:
  • Remove forced line resets between inline text/link segments so mixed inline content composes in one flow stream.
  • Represent inline <br> as a hard line-break token in inline layout (not a synthetic space).
  • Preserve one logical focus index per link while allowing wrapped link chunks to span lines.
  1. Tests:
  • Add fixtures for mixed text/link/text on one line and overflow-wrap behavior.
  • Add fixture where inline <br> appears inside <p> and assert mandatory line break.
  1. Accept:
  • Inline paragraph output matches spec-equivalent flow for mixed runs and <br> behavior.
  1. Notes:
  • Spec anchor refs: WAP-191 section 9.9 and section 11.8.4 (br line-break mandate).

B5-03 Paragraph mode/alignment semantics follow-up

  1. Requirement IDs: WML-R-022, WML-R-026
  2. Status: todo
  3. Depends On: B5-02
  4. Files:
  • engine-wasm/engine/src/layout/flow_layout.rs
  • engine-wasm/engine/src/parser/wml_parser/*
  • engine-wasm/engine/src/runtime/card.rs
  • engine-wasm/engine/tests/fixtures/*
  1. Build:
  • Parse and retain paragraph mode and align attributes.
  • Implement card-local default inheritance for wrap/alignment across significant paragraphs.
  • Enforce nowrap behavior and add deterministic handling for &nbsp; and optional soft-hyphen break points.
  1. Tests:
  • Add paragraph-mode fixture matrix (wrap, nowrap, inherited mode, mixed significant/insignificant paragraphs).
  • Add non-breaking-space and soft-hyphen fixtures.
  1. Accept:
  • Paragraph layout mode/alignment behavior is deterministic and matches section 11.8.3 expectations.
  1. Notes:
  • Spec anchor refs: WAP-191 section 11.8.3 (paragraph wrap/alignment + white-space break rules).

C5-01 Table element rendering semantics follow-up

  1. Requirement IDs: WML-R-024
  2. Status: todo
  3. Depends On: M1-07
  4. Files:
  • engine-wasm/engine/src/parser/wml_parser/*
  • engine-wasm/engine/src/runtime/node.rs
  • engine-wasm/engine/src/layout/flow_layout.rs
  • engine-wasm/engine/tests/fixtures/*
  1. Build:
  • Parse table/tr/td structure with required columns attribute.
  • Implement row normalization semantics: pad missing cells and aggregate overflow cells into the last column with single inter-word separator.
  • Provide deterministic rendering fallback suitable for small displays.
  1. Tests:
  • Add table fixtures covering exact columns, underflow row padding, overflow row aggregation, and alignment designator handling.
  1. Accept:
  • Table behavior is deterministic and follows section 11.8.5-11.8.8 structure rules.
  1. Notes:
  • Spec anchor refs: WAP-191 section 11.8.5 through 11.8.8.

C5-02 Preformatted text semantics follow-up

  1. Requirement IDs: WML-R-025
  2. Status: todo
  3. Depends On: B5-03
  4. Files:
  • engine-wasm/engine/src/parser/wml_parser/*
  • engine-wasm/engine/src/runtime/node.rs
  • engine-wasm/engine/src/layout/flow_layout.rs
  • engine-wasm/engine/tests/fixtures/*
  1. Build:
  • Parse <pre> blocks and preserve preformatted text intent in runtime nodes.
  • Implement best-effort preformatted rendering behavior: preserve internal whitespace and optionally disable auto-wrap.
  1. Tests:
  • Add pre fixtures with significant spacing and long-line behavior across viewport widths.
  1. Accept:
  • Preformatted content renders deterministically with preserved spacing semantics.
  1. Notes:
  • Spec anchor refs: WAP-191 section 11.8.9 (xml:space="preserve" and best-effort preformatted behavior).

C5-03 Deck structure and metadata semantics completion

  1. Requirement IDs: WML-R-010, WML-R-018
  2. Status: done
  3. Depends On: M1-07
  4. Files:
  • engine-wasm/engine/src/parser/wml_parser/*
  • engine-wasm/engine/src/runtime/deck.rs
  • engine-wasm/engine/src/runtime/card.rs
  • engine-wasm/contracts/wml-engine.ts
  • engine-wasm/engine/tests/fixtures/*
  1. Build:
  • Parse and retain head, template, access, and meta structures needed for runtime semantics and host policy hooks.
  • Parse/retain card context attributes (newcontext, ordered) with deterministic defaults and exposure paths.
  • Enforce deterministic validation for duplicate/invalid meta constraints where applicable.
  1. Tests:
  • Fixture matrix for head/template inheritance, card context defaults, and meta constraint validation.
  1. Accept:
  • Deck metadata required for policy/navigation semantics is available and stable across native/wasm targets.
  1. Notes:
  • Spec anchor refs: WAP-191 section 11.3 through 11.5, section 10.2.
  • Progress: WML root/head ordering, access uniqueness/retention, and ordered meta validation/retention are directly tested across native and WASM entry paths.
  • Referring-URI access defaults/matching are enforced before deck transition at the engine/host boundary; root/card language and newcontext/ordered metadata are retained and exposed across native/WASM/host contracts.
  • Card event/timer/content grammar, source render order, and go-only newcontext reset behavior have focused native/WASM/host tests plus executable WML-202 story evidence.

C5-04 Task/event pipeline and variable-substitution conformance

  1. Requirement IDs: WML-R-011, WML-R-012, WML-R-013, WML-R-015, WML-R-016, WML-R-017
  2. Status: todo
  3. Depends On: A5-02, A5-03
  4. Files:
  • engine-wasm/engine/src/lib.rs
  • engine-wasm/engine/src/runtime/*
  • engine-wasm/engine/src/parser/wml_parser/*
  • engine-wasm/engine/tests/fixtures/*
  1. Build:
  • Implement deterministic task/event pipeline semantics for go|prev|noop|refresh with onevent/do integration.
  • Implement variable substitution in required contexts with proper timing, undefined-variable behavior, and conversion handling.
  • Enforce event-binding/task conflict validation rules and deterministic failure behavior.
  1. Tests:
  • Add process-order fixtures for task execution and failure rollback.
  • Add variable-substitution fixtures for text, href, and vdata contexts including conversion forms.
  1. Accept:
  • Task/event/variable behavior is deterministic and matches spec-driven ordering expectations for covered flows.
  1. Notes:
  • Spec anchor refs: WAP-191 section 9.5, 9.10, 10.3, 12.5.

C5-05 Form controls and commit semantics completion

  1. Requirement IDs: WML-R-019
  2. Status: todo
  3. Depends On: B5-01, C5-04
  4. Files:
  • engine-wasm/engine/src/parser/wml_parser/*
  • engine-wasm/engine/src/runtime/*
  • engine-wasm/engine/src/layout/*
  • engine-wasm/engine/tests/fixtures/*
  1. Build:
  • Complete select/option/optgroup/input/fieldset runtime semantics for initialization, selection state, and variable commit behavior.
  • Implement minimum-conformance input-mask validation and deterministic invalid-entry handling.
  1. Tests:
  • Form fixture matrix for single-select, multi-select, input defaults, invalid commits, and deterministic variable updates.
  1. Accept:
  • Form/control behavior aligns with defined WML runtime semantics for implemented profile.
  1. Notes:
  • Spec anchor refs: WAP-191 section 11.6.
  • WML-204 grouped-control evidence validates fieldset/optgroup attributes and content, rejects empty grouping leaves, preserves transparent child processing across native/WASM parsing, and exercises the fallback through both canonical stories. Optional grouping presentation and capability declaration remain unassessed follow-up scope.

Suggested First Sprint (7 tickets)

  1. A1-01
  2. A1-02
  3. A1-03
  4. A2-01
  5. A3-01
  6. A3-02
  7. A4-01

This keeps scope in strict MVP while removing current implementation risk around parsing, focus, wrapping, and boundary behavior.

Exit Criteria for Phase A

  1. All A* tickets are done.
  2. Requirement IDs WML-R-001..009, WML-R-020, WBXML-R-001 have passing tests.
  3. Host sample can:
  • load a deck via loadDeckContext
  • navigate via focus + enter
  • execute #cardId transitions
  • expose deterministic render output and metadata