Site history and delivery workspace

The published documentation surface now carries a local delivery workspace at history.html. It is a browser-mediated equivalent for controls that cannot safely run from a static page. It never presents the page as the installed desktop application or as a PBX runtime.

Behavior

  • Visitor-owned history is append-only in browser storage. Each event has a timestamp, a registered action enum, and bounded allowlisted parameters. Localized sentences are rendered from those parameters, while no free-form summary or content field is persisted. Search, date range, and action filters compose, and a full anchored regex builder is available beside each search field.
  • The history panel has a bounded local JSON picker for the versioned round trip. It rejects from the selected file's declared file.size before allocation, reads only a 512 KiB slice, then measures the resulting ArrayBuffer before UTF-8 decoding. It rejects invalid UTF-8, eight-level nesting, duplicate keys, unknown or unsafe keys, invalid timestamps, registered actions with unknown parameter keys, safe counts capped at 100,000, or byte values capped at 64 MiB. Valid records are appended, never used to replace live state. A dedicated history-import event records retained, refused, existing-live-event truncation, and imported-event truncation counts. Empty, refused-only, duplicate-only, and zero-retained imports are distinguished and preserve every live event. Their separate path-free no-op audit stores the validated export schema and event schema versions without consuming a history slot.
  • Restore does not rewrite an earlier event. It appends a new restored event that names the source event identifier. Redacted JSON and Markdown exports state that personal vocabulary, credentials, paths, and file contents were omitted.
  • The changelog viewer shows the 89 product release tags by default. Optional upstream tag history is clearly separated behind an explicit local choice. Every record has a valid full object identifier, date, category, factual summary, and full commit URL. Its filtered view can be copied or exported to Markdown.
  • Provider-authored Markdown is escaped before the small supported subset is rendered. Script, image, raw HTML, and executable links are not interpreted.
  • A local file can be selected for inspection and export. External-editor opening remains explicitly unavailable because a normal browser does not expose a verified local path. The page provides the official Visual Studio Code download route instead, and never requests credentials.
  • The browser-extension download equivalent uses the File System Access API when available. Start opens a real destination picker, progress is measured from actual chunks written, cancellation aborts the writable stream, and completion is reported only after the stream closes. Unsupported browsers remain unavailable rather than receiving a simulated transfer.
  • Forge publishing is a partial generic-provider preview. The visitor reviews source, destination, account, owner, repository, and copy or fork route before opening the provider's own page. No source or destination operation occurs on this page. The provider handles sign-in and publication. No credential is collected, stored, or sent by this page, and the registry records that publication itself is not implemented here.
  • The update surface reads the bundled release-manifest equivalent and reports unavailable, available, downloading, ready, or failed only when the manifest carries that state and a valid full commit identifier. A static page cannot install an application or claim that an update was applied.
  • The shared delivery rail exposes ordinary persisted route navigation with pinning. Static-host limitations are stated beside it: grouping and reordering are not offered by this route, and the markup does not claim incomplete navigation is a full tab implementation.
  • Every select control receives its own local filter field and adjacent anchored regex builder. Date filters also provide validated ISO ranges and named presets.
  • A bounded local export operation disables re-entry, exposes real cancellation, and reports preparation progress while processing the current event set. Prepared-export editor fields are separate from selected-file transfer fields. Its versioned delivery state distinguishes preparing, prepared, handoff-started, handoff-unverified, handoff-cancelled, and handoff-failed. A browser handoff never becomes a 100 percent completion claim merely because the browser accepted a click.

Configuration

The module is console/site/history-delivery.js, loaded by the shared console/site/app.js registration on the six primary pages and directly by generated documentation pages. State schema version 3 uses the versioned ding-pbx-site-history-delivery-v1 browser-storage key with a maximum of 250 events. Legacy schema-2 summary/details records are migrated only when their action parameters can be safely mapped to the structured event enum. Both legacy and current normalization require the canonical lowercase event ID pattern, keep a seen-ID set, and require a finite parsed timestamp before normalization. Unsafe or colliding IDs and malformed timestamps are counted as refused records, so the migration and normalization audits show the loss rather than silently sanitizing it. The migration records imported, omitted, refused, and retention-truncated counts, persists immediately, and never reports loss as lossless success. Current schema-3 records are normalized and audited before replacement when malformed records are refused or omitted. The future-version refusal audit is stored separately, disclosed in its own panel, and omitted from ordinary exports; its refusal reason is bounded and redacted. The migration event is marked recorded only after its append result is verified, and a refused append remains in that audit. Structured parameters are localized at render time, and search uses only a bounded projection of the normalized parameters. Export schema version 2 carries the complete structured event records needed for JSON round-trip import, with no free-form event text field. Its local picker validates that exact envelope after rejecting by file.size and reading only the bounded slice, then rejects duplicate, unknown, unsafe, malformed, oversized, or out-of-bound data, rejects imported records whose parameter object has any unknown key, and appends accepted records without replacing live state. New history-import records carry imported, refused, existingTruncated, and importTruncated; older persisted truncated records are migrated without dropping their count, while new file imports never normalize unknown keys. Empty, refused-only, duplicate-only, and zero-retained attempts are distinguished and written to a separate path-free no-op audit carrying the validated export and event schema versions. Markdown is explicitly presentation-only and carries the rendered row.text table, active filters, row count, and an omission disclosure. console/site/generate-changelog.mjs produces console/site/changelog-data.js from every local tag, and console/site/release-manifest.js records the versioned verified release state. Failed manifests may omit assets when their exact commit and reason are present, while available, downloading, and ready states require validated assets. The module does not make a runtime network request. console/site/build.mjs validates changelog completeness, exact tag targets, dates, summaries, the product-release split, and the manifest schema, then copies the module and history.html into deterministic published output, adds a real delivery mount host to generated article pages, loads the full builder and command-palette stack, and wires the workspace into those pages.

Failure modes

Browser storage may be unavailable, a clipboard request may be refused, a browser may not expose File System Access, a provider may require a new sign-in, or a static page may have no verified release manifest. Each state remains visible beside the action that encountered it and offers retry, settings, or the official editor download route where applicable. None of these conditions is converted into a fake success.

Verification

The source inventory names the history workspace, shared module registration, generated-page wiring, redacted export boundary, safe Markdown renderer, download state machine, forge boundary, editor fallback, and update status controls. Manual verification should exercise the real published artifact from a clean browser profile, including reload persistence, filter composition, invalid regex feedback, restore-as-new-event, retention preview and prune event, export omission text, File System Access cancellation and stream-close completion, provider flow refusal recovery, and static update honesty. No browser, build, test, lint, or capture run was performed in this lane.

Suggested articles