npm - @fullstack-webapp/document-shell - Versions diffs - 0.1.0-beta.3 → 0.1.0-beta.4 - Mend

@fullstack-webapp/document-shell 0.1.0-beta.3 → 0.1.0-beta.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (5) hide show

package/README.md CHANGED Viewed

@@ -155,6 +155,18 @@ The commit waits for that gate, marks `<html data-app-ready="true">`, removes
 the element carrying `data-document-shell-static`, and always fails open so a
 broken stylesheet cannot leave a permanent overlay.
+A consumer whose static projection reveals delayed content (for example a
+content placeholder that only appears after a short race with the runtime and
+then stays visible for a minimum duration) can declare an absolute
+reveal-not-before deadline on the projection element via the exported
+`documentShellRevealNotBeforeAttribute` at the moment that content becomes
+visible. The loaded handoff then waits until the deadline before writing
+`data-app-ready` and removing the projection. Only a finite, future deadline
+that is still inside both the package's bounded hold horizon and the runtime
+stylesheet gate's recorded fail-open deadline is honored; absent, invalid, or
+expired declarations leave the loaded handoff immediate, and stylesheet `error`, `timeout`, and absence always reveal
+immediately. See the integration guide for the declaration contract.
 For the full file-by-file procedure, safe-area effect example, verification
 checklist, and failure guide, see [Integration guide](docs/integration.md).
@@ -164,7 +176,7 @@ checklist, and failure guide, see [Integration guide](docs/integration.md).
 | --- | --- |
 | `@fullstack-webapp/document-shell` | Typed HTML/CSS/script boundaries, document composition types, compiler, structural validation, and the shared-default safe-area bridge. |
 | `@fullstack-webapp/document-shell/vite` | The Vite HTML producer, optional runtime-stylesheet gate, and final emitted-document validator. |
-| `@fullstack-webapp/document-shell/client` | The framework-neutral, one-shot runtime handoff. |
+| `@fullstack-webapp/document-shell/client` | The framework-neutral, one-shot runtime handoff and its package-owned DOM contracts, including the optional reveal-not-before deadline. |
 | `@fullstack-webapp/document-shell/reference` | Reference-application safe-area rollout used to retain existing evidence while profiles mature; it is not a consumer profile selector. |
 The current beta catalog projects all four accepted iOS standalone portrait
@@ -213,6 +225,10 @@ an arbitrary callback with `Function#toString()`.
 - The current safe-area runtime matches observable browser geometry and
   platform signals, not marketing device names. Unsupported geometry fails
   open and receives no reserve.
+- A reveal-not-before declaration can delay only a stylesheet `loaded`
+  handoff, and never past the runtime stylesheet gate's recorded fail-open
+  deadline; `error`, `timeout`, and `absent` outcomes and missing, invalid, or
+  expired declarations keep the immediate fail-open behavior.
 ## Development

package/dist/client.d.ts CHANGED Viewed

@@ -1,6 +1,16 @@
 export declare const documentShellReadyAttribute = "data-app-ready";
 export declare const documentShellStaticAttribute = "data-document-shell-static";
 export declare const documentShellRuntimeStylesheetId = "runtime-stylesheet";
+/**
+ * Runtime-declared reveal-not-before deadline. The consumer's parser startup
+ * effect writes an absolute epoch-millisecond deadline into this attribute on
+ * the element carrying {@link documentShellStaticAttribute} at the moment the
+ * projection's delayed content actually becomes visible. A loaded stylesheet
+ * handoff waits until that deadline before writing `data-app-ready` and
+ * removing the projection; absent, invalid, or expired deadlines leave the
+ * loaded handoff immediate, and `error`/`timeout`/`absent` always fail open.
+ */
+export declare const documentShellRevealNotBeforeAttribute = "data-document-shell-reveal-not-before";
 export type DocumentShellHandoffResult = Readonly<{
     status: 'revealed';
     stylesheet: 'loaded' | 'error' | 'timeout' | 'absent';

package/dist/client.js CHANGED Viewed

@@ -1,7 +1,24 @@
 export const documentShellReadyAttribute = 'data-app-ready';
 export const documentShellStaticAttribute = 'data-document-shell-static';
 export const documentShellRuntimeStylesheetId = 'runtime-stylesheet';
+/**
+ * Runtime-declared reveal-not-before deadline. The consumer's parser startup
+ * effect writes an absolute epoch-millisecond deadline into this attribute on
+ * the element carrying {@link documentShellStaticAttribute} at the moment the
+ * projection's delayed content actually becomes visible. A loaded stylesheet
+ * handoff waits until that deadline before writing `data-app-ready` and
+ * removing the projection; absent, invalid, or expired deadlines leave the
+ * loaded handoff immediate, and `error`/`timeout`/`absent` always fail open.
+ */
+export const documentShellRevealNotBeforeAttribute = 'data-document-shell-reveal-not-before';
 const handoffs = new WeakMap();
+/**
+ * Maximum wall-clock horizon accepted for an optional reveal hold. The
+ * stylesheet bootstrap normally supplies the same three-second gate, while
+ * this independent bound also survives wall-clock adjustments between the
+ * declaration and the loaded handoff.
+ */
+const revealHoldHorizonMs = 3_000;
 export function commitDocumentShellRuntime() {
     if (typeof document === 'undefined') {
         return Promise.reject(new Error('Document shell runtime handoff requires a browser document'));
@@ -20,6 +37,10 @@ export function commitDocumentShellRuntime() {
     const pending = {};
     root.setAttribute('data-document-shell-runtime-committed', 'true');
     const cleanup = () => {
+        if (pending.holdTimer !== undefined) {
+            window.clearTimeout(pending.holdTimer);
+            pending.holdTimer = undefined;
+        }
         if (pending.fallbackTimer !== undefined)
             window.clearTimeout(pending.fallbackTimer);
         if (pending.revealFrame !== undefined)
@@ -27,7 +48,7 @@ export function commitDocumentShellRuntime() {
         stylesheet?.removeEventListener('load', handleLoad);
         stylesheet?.removeEventListener('error', handleError);
     };
-    const reveal = (stylesheetStatus) => {
+    const commitReveal = (stylesheetStatus) => {
         if (finished)
             return;
         finished = true;
@@ -36,6 +57,18 @@ export function commitDocumentShellRuntime() {
         document.querySelector(`[${documentShellStaticAttribute}]`)?.remove();
         resolveHandoff({ status: 'revealed', stylesheet: stylesheetStatus });
     };
+    const reveal = (stylesheetStatus) => {
+        if (finished)
+            return;
+        if (stylesheetStatus === 'loaded') {
+            const holdUntil = readRevealNotBeforeDeadline();
+            if (holdUntil !== null) {
+                scheduleRevealHold(holdUntil);
+                return;
+            }
+        }
+        commitReveal(stylesheetStatus);
+    };
     const revealAfterStylesApply = () => {
         if (finished || pending.revealFrame !== undefined)
             return;
@@ -75,4 +108,50 @@ export function commitDocumentShellRuntime() {
         : 0;
     pending.fallbackTimer = window.setTimeout(() => reveal('timeout'), fallbackDelay);
     return handoff;
+    /**
+     * Reads the reveal-not-before declaration at the moment the loaded handoff
+     * is about to reveal, so a deadline declared while the stylesheet was still
+     * loading is honored. Only a finite absolute deadline that is strictly in
+     * the future and still inside the runtime stylesheet gate's recorded
+     * fail-open deadline is honored; every other value is treated as absent or
+     * expired, keeping the loaded handoff immediate and guaranteeing that the
+     * projection can never outlive the stylesheet gate.
+     */
+    function readRevealNotBeforeDeadline() {
+        const projection = document.querySelector(`[${documentShellStaticAttribute}]`);
+        const raw = projection?.getAttribute(documentShellRevealNotBeforeAttribute);
+        if (!raw)
+            return null;
+        const deadline = Number(raw);
+        const now = Date.now();
+        if (!Number.isFinite(deadline) || deadline <= now)
+            return null;
+        const gateDeadline = Number(stylesheet?.dataset.failureDeadline);
+        const ceiling = Math.min(now + revealHoldHorizonMs, Number.isFinite(gateDeadline) ? gateDeadline : Number.POSITIVE_INFINITY);
+        return deadline <= ceiling ? deadline : null;
+    }
+    /**
+     * Defers the loaded reveal until the declared deadline. Wall-clock time
+     * preserves the absolute deadline during normal operation, while a monotonic
+     * ceiling limits the wait to the delay accepted when it was scheduled. The
+     * fired timer is cleared before re-evaluation so an early fire reschedules;
+     * a backward wall-clock adjustment cannot extend the inert projection beyond
+     * the original bounded delay. The timer shares the handoff cleanup lifecycle.
+     */
+    function scheduleRevealHold(deadline) {
+        if (pending.holdTimer !== undefined)
+            return;
+        const maximumDelay = Math.min(revealHoldHorizonMs, Math.max(0, deadline - Date.now()));
+        const monotonicDeadline = window.performance.now() + maximumDelay;
+        const wait = () => {
+            pending.holdTimer = undefined;
+            const remaining = Math.min(deadline - Date.now(), monotonicDeadline - window.performance.now());
+            if (remaining > 0) {
+                pending.holdTimer = window.setTimeout(wait, remaining);
+                return;
+            }
+            commitReveal('loaded');
+        };
+        pending.holdTimer = window.setTimeout(wait, maximumDelay);
+    }
 }

package/docs/integration.md CHANGED Viewed

@@ -179,6 +179,110 @@ The resolved result records whether the runtime stylesheet was `loaded`,
 `error`, `timeout`, or `absent`. Every result is a revealed state. Error and
 timeout are fail-open outcomes, not thrown errors.
+### Declare a reveal-not-before deadline (optional)
+A projection may reveal part of its content only after a short race with the
+runtime, then keep that delayed content visible for a minimum duration. CSS can
+delay the delayed content's appearance, but it cannot stop the loaded handoff
+from removing the whole projection mid-duration. For that surface the consumer
+declares an absolute reveal-not-before deadline on the static projection at the
+moment the delayed content actually becomes visible; the loaded handoff then
+waits until that deadline before writing the readiness attribute and removing
+the projection.
+The deadline is a package-owned DOM contract, not a hand-written attribute:
+```ts
+import {
+  commitDocumentShellRuntime,
+  documentShellRevealNotBeforeAttribute,
+} from '@fullstack-webapp/document-shell/client'
+```
+The consumer's parser startup effect writes an absolute epoch-millisecond
+deadline (`Date.now() + minimumVisibleMs`) into
+`documentShellRevealNotBeforeAttribute` on the element carrying
+`data-document-shell-static`. Declare it only when the delayed content is
+actually visible: when the runtime won the race and the projection was already
+revealed, there is nothing to hold, and a later declaration is simply too late.
+A minimal runtime effect, composed by the renderer, can look like this:
+```ts
+import {
+  cssText,
+  htmlFragment,
+  inlineScript,
+  type DocumentShellComposition,
+} from '@fullstack-webapp/document-shell'
+import { documentShellRevealNotBeforeAttribute } from '@fullstack-webapp/document-shell/client'
+const revealDelayMs = 150        // surface policy, chosen by the consumer
+const minimumVisibleMs = 250     // surface policy, chosen by the consumer
+const composition: DocumentShellComposition = {
+  // ...
+  startupEffects: {
+    beforePaint: [
+      {
+        marker: 'data-reveal-declarer',
+        script: inlineScript(`
+          (() => {
+            const revealDelay = ${revealDelayMs}
+            const minimumVisible = ${minimumVisibleMs}
+            const selector = '[data-document-shell-static]'
+            setTimeout(() => {
+              const projection = document.querySelector(selector)
+              // Still projected at the reveal-delay boundary means the delayed
+              // content is becoming visible now: keep it for its minimum
+              // visible duration before the handoff may reveal.
+              if (projection) {
+                projection.setAttribute(
+                  '${documentShellRevealNotBeforeAttribute}',
+                  String(Date.now() + minimumVisible),
+                )
+              }
+            }, revealDelay)
+          })()
+        `),
+      },
+    ],
+  },
+}
+```
+The values shown are examples; the delay and the minimum visible duration are
+consumer surface policy and belong to the surface that owns the pending
+experience, not to Document Shell.
+Semantics:
+- Only a normal stylesheet `loaded` handoff can wait for a deadline.
+  Stylesheet `error`, `timeout`, and absence keep their immediate fail-open
+  reveal and are never blocked by a declaration.
+- The package honors a declaration only when it is a finite absolute timestamp,
+  strictly after the current time, within the package's three-second defensive
+  hold horizon, and no later than the runtime stylesheet gate's recorded
+  fail-open deadline (the same absolute deadline that already bounds the whole
+  handoff). Every other value — absent, non-numeric, zero,
+  negative, `Infinity`, expired, or too far in the future — is treated as
+  expired, and the loaded handoff reveals immediately exactly as without a
+  declaration.
+- The deadline is sampled when the loaded reveal is about to run. A
+  declaration that lands while the stylesheet is still loading or between the
+  load event and the apply frame is honored; a declaration that lands after the
+  reveal already ran cannot resurrect the projection.
+- The wait is a package timer with the same cleanup lifecycle as the rest of
+  the handoff. Repeated `commitDocumentShellRuntime()` calls return the same
+  document-level promise and never create a second timer, and the projection is
+  still removed exactly once. The absolute wall-clock deadline is also bounded
+  by the monotonic delay accepted when scheduling, so moving the system clock
+  backward cannot extend the hold indefinitely.
+The bounded rule keeps the existing fail-open guarantee intact: an inert
+projection can never outlive the runtime stylesheet gate, so a malformed or
+mistaken declaration cannot pin the overlay past the point the package would
+otherwise have released it.
 ## 6. Keep static and runtime geometry identical
 The most common integration defect is not lifecycle; it is two shells using
@@ -323,6 +427,23 @@ The commit hook is mounted too early, or a consumer reimplemented the handoff.
 Place it inside the persistent runtime shell and call only
 `commitDocumentShellRuntime()`.
+### A delayed projection disappears before its minimum visible duration ends
+The delayed content's appearance is timed with CSS, but the loaded handoff
+still removes the projection as soon as the stylesheet applied. Declare a
+reveal-not-before deadline (see the optional seam above) at the moment the
+delayed content becomes visible instead of adding a competing timer in the
+framework hook.
+### A declared reveal-not-before deadline never seems to hold
+The declaration must live on the element carrying `data-document-shell-static`
+as `documentShellRevealNotBeforeAttribute`, hold an absolute epoch-millisecond
+timestamp inside both the bounded hold horizon and the runtime stylesheet gate,
+and land before the loaded reveal runs. A static far-future value in the emitted
+HTML is ignored by design so it cannot pin the overlay; declare it from the startup effect when
+the delayed content is actually visible.
 ### Icons, labels, active state, or tab-bar height still move
 The static and runtime shells do not share all geometry inputs. Compare font

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@fullstack-webapp/document-shell",
-  "version": "0.1.0-beta.3",
+  "version": "0.1.0-beta.4",
   "description": "Parser-visible startup shell compiler, Vite HTML pipeline, and framework-neutral runtime handoff for web applications.",
   "license": "MIT",
   "type": "module",