@fullstack-webapp/document-shell 0.0.0

package/dist/safe-area-bridge.js

@@ -0,0 +1,226 @@
+import { safeAreaCompatibilityProfiles, } from "./safe-area-profiles.js";
+function assertProfiles(profiles) {
+    const ids = new Set();
+    const signatures = new Set();
+    for (const profile of profiles) {
+        if (ids.has(profile.id))
+            throw new Error(`Duplicate safe-area profile id: ${profile.id}`);
+        ids.add(profile.id);
+        if (!Number.isInteger(profile.minimumRuntimeVersion[0]) ||
+            profile.minimumRuntimeVersion[0] < 0 ||
+            !Number.isInteger(profile.minimumRuntimeVersion[1]) ||
+            profile.minimumRuntimeVersion[1] < 0) {
+            throw new Error(`Safe-area profile ${profile.id} has an invalid minimum runtime version`);
+        }
+        if (profile.reserve.bottom <= 0) {
+            throw new Error(`Safe-area profile ${profile.id} must provide a positive bottom reserve`);
+        }
+        const signature = JSON.stringify({
+            platform: profile.platform,
+            displayMode: profile.displayMode,
+            orientation: profile.orientation,
+            screen: profile.screen,
+            devicePixelRatio: profile.devicePixelRatio,
+        });
+        if (signatures.has(signature)) {
+            throw new Error(`Safe-area profile ${profile.id} overlaps another runtime matcher`);
+        }
+        signatures.add(signature);
+    }
+}
+function assertDomEffect(domEffect) {
+    if (!domEffect.reserveBottomCssVariable.startsWith('--')) {
+        throw new Error('Safe-area DOM effect CSS variable must start with --');
+    }
+    for (const [label, name] of Object.entries({
+        profile: domEffect.profileAttribute,
+        orientation: domEffect.orientationAttribute,
+        reserve: domEffect.reserveAttribute,
+    })) {
+        if (name !== undefined && !name.startsWith('data-')) {
+            throw new Error(`Safe-area DOM effect ${label} attribute must start with data-`);
+        }
+    }
+    for (const [label, property] of Object.entries({
+        reserve: domEffect.windowStateProperty,
+        result: domEffect.resultStateProperty,
+    })) {
+        if (property !== undefined && !/^__[A-Za-z][A-Za-z0-9_]*$/.test(property)) {
+            throw new Error(`Safe-area DOM effect ${label} state property must use a private __name`);
+        }
+    }
+}
+function createSafeAreaBridgeForRollouts({ domEffect, diagnosticOverride, }, rollouts) {
+    const stableFrames = 2;
+    const timeoutMs = 3_000;
+    assertProfiles(safeAreaCompatibilityProfiles);
+    assertDomEffect(domEffect);
+    const runtimeProfiles = safeAreaCompatibilityProfiles
+        .filter((profile) => rollouts.has(profile.rollout))
+        .map((profile) => ({
+        id: profile.id,
+        platform: profile.platform,
+        minimumRuntimeVersion: profile.minimumRuntimeVersion,
+        displayMode: profile.displayMode,
+        orientation: profile.orientation,
+        screen: profile.screen,
+        devicePixelRatio: profile.devicePixelRatio,
+        reserve: profile.reserve,
+    }));
+    const diagnosticSelection = diagnosticOverride
+        ? `const diagnosticOverride = ${JSON.stringify({
+            enabledAttribute: diagnosticOverride.enabledAttribute,
+            enabledValue: diagnosticOverride.enabledValue ?? 'true',
+            queryParameter: diagnosticOverride.queryParameter,
+            bottom: diagnosticOverride.bottom,
+        })}
+  const diagnosticEnabled = document.documentElement.getAttribute(diagnosticOverride.enabledAttribute) === diagnosticOverride.enabledValue
+  const diagnosticBottom = Number(new URL(location.href).searchParams.get(diagnosticOverride.queryParameter))
+  const selectedProfile = diagnosticEnabled && diagnosticBottom === diagnosticOverride.bottom
+    ? { id: 'diagnostic-override', orientation, reserve: { bottom: diagnosticBottom } }
+    : matchedProfile`
+        : 'const selectedProfile = matchedProfile';
+    const bootstrap = `(() => {
+  const profiles = ${JSON.stringify(runtimeProfiles)}
+  const domEffect = ${JSON.stringify(domEffect)}
+  const applyDomUpdate = (update) => {
+    const root = document.documentElement
+    if (update.kind === 'reserve') {
+      if (domEffect.profileAttribute) root.setAttribute(domEffect.profileAttribute, update.profile)
+      if (domEffect.orientationAttribute) root.setAttribute(domEffect.orientationAttribute, update.orientation)
+      if (domEffect.reserveAttribute) root.setAttribute(domEffect.reserveAttribute, String(update.bottom))
+      root.style.setProperty(domEffect.reserveBottomCssVariable, update.bottom + 'px')
+      if (domEffect.windowStateProperty) {
+        window[domEffect.windowStateProperty] = {
+          profile: update.profile,
+          orientation: update.orientation,
+          bottom: update.bottom,
+        }
+      }
+      return
+    }
+    if (domEffect.reserveAttribute) root.removeAttribute(domEffect.reserveAttribute)
+    root.style.removeProperty(domEffect.reserveBottomCssVariable)
+    if (domEffect.windowStateProperty) window[domEffect.windowStateProperty] = undefined
+    if (update.reason === 'orientation-changed') {
+      if (domEffect.profileAttribute) root.removeAttribute(domEffect.profileAttribute)
+      if (domEffect.orientationAttribute) root.removeAttribute(domEffect.orientationAttribute)
+    }
+  }
+  const platform = /iPhone|iPad|iPod/.test(navigator.userAgent)
+    ? 'ios'
+    : /Android/.test(navigator.userAgent)
+      ? 'android'
+      : 'unknown'
+  const versionMatch = platform === 'ios'
+    ? navigator.userAgent.match(/Version[/](\\d+)[.](\\d+)/)
+    : undefined
+  const runtimeVersion = versionMatch ? [Number(versionMatch[1]), Number(versionMatch[2])] : undefined
+  const standalone = matchMedia('(display-mode: standalone)').matches || navigator.standalone === true
+  const orientation = matchMedia('(orientation: portrait)').matches ? 'portrait' : 'landscape'
+  const versionAtLeast = (version, minimumVersion) => {
+    if (!version) return false
+    const value = version[0] * 1000 + version[1]
+    const minimum = minimumVersion[0] * 1000 + minimumVersion[1]
+    return value >= minimum
+  }
+  const matchedProfile = profiles.find((profile) =>
+    profile.platform === platform &&
+    versionAtLeast(runtimeVersion, profile.minimumRuntimeVersion) &&
+    profile.displayMode === (standalone ? 'standalone' : 'browser') &&
+    profile.orientation === orientation &&
+    profile.screen.width === screen.width &&
+    profile.screen.height === screen.height &&
+    profile.devicePixelRatio === devicePixelRatio
+  )
+  ${diagnosticSelection}
+  if (!selectedProfile) {
+    if (domEffect.resultStateProperty) {
+      window[domEffect.resultStateProperty] = { status: 'inactive' }
+    }
+    return
+  }
+
+  const bottom = selectedProfile.reserve.bottom
+  const reserveUpdate = {
+    kind: 'reserve',
+    profile: selectedProfile.id,
+    orientation: selectedProfile.orientation,
+    bottom,
+  }
+  applyDomUpdate(reserveUpdate)
+
+  let previousViewport
+  let stableViewportFrames = 0
+  let finished = false
+  let nativeBottom = 0
+  let timeoutHandle
+  const reportResult = (status, reason, nativeBottom) => {
+    if (!domEffect.resultStateProperty) return
+    window[domEffect.resultStateProperty] = {
+      profile: selectedProfile.id,
+      status,
+      reason,
+      nativeBottom,
+      bottom,
+    }
+  }
+  const stopOrientationWatch = () => {
+    window.removeEventListener('orientationchange', releaseForOrientationChange)
+    window.removeEventListener('resize', releaseForOrientationChange)
+  }
+  const releaseForOrientationChange = () => {
+    if (matchMedia('(orientation: portrait)').matches === (orientation === 'portrait')) return
+    applyDomUpdate({ ...reserveUpdate, kind: 'release', reason: 'orientation-changed' })
+    clearTimeout(timeoutHandle)
+    finished = true
+    stopOrientationWatch()
+    reportResult('released', 'orientation-changed', nativeBottom)
+  }
+  const finish = (status, reason, nativeBottom, keepOrientationWatch = false) => {
+    if (finished) return
+    finished = true
+    clearTimeout(timeoutHandle)
+    if (!keepOrientationWatch) stopOrientationWatch()
+    reportResult(status, reason, nativeBottom)
+  }
+  window.addEventListener('orientationchange', releaseForOrientationChange)
+  window.addEventListener('resize', releaseForOrientationChange)
+  timeoutHandle = setTimeout(() => {
+    finish('unresolved', 'timeout', nativeBottom, true)
+  }, ${timeoutMs})
+  const sample = () => {
+    if (finished) return
+    if (matchMedia('(orientation: portrait)').matches !== (orientation === 'portrait')) {
+      releaseForOrientationChange()
+      return
+    }
+    if (document.visibilityState !== 'visible') {
+      requestAnimationFrame(sample)
+      return
+    }
+    const probe = document.querySelector('[data-document-shell-native-safe-area]')
+    nativeBottom = probe ? Number.parseFloat(getComputedStyle(probe).paddingBottom) || 0 : 0
+    const viewport = [nativeBottom, innerWidth, innerHeight, window.visualViewport?.width ?? 0, window.visualViewport?.height ?? 0, window.visualViewport?.offsetTop ?? 0].join(':')
+    stableViewportFrames = viewport === previousViewport ? stableViewportFrames + 1 : 1
+    previousViewport = viewport
+    if (nativeBottom >= bottom && stableViewportFrames >= ${stableFrames}) {
+      applyDomUpdate({ ...reserveUpdate, kind: 'release', reason: 'native-stable' })
+      finish('released', 'native-stable', nativeBottom)
+      return
+    }
+    requestAnimationFrame(sample)
+  }
+  requestAnimationFrame(sample)
+})()`;
+    return {
+        beforePaint: bootstrap,
+        probeHtml: '    <div data-document-shell-native-safe-area aria-hidden="true" style="position:fixed;visibility:hidden;pointer-events:none;padding-bottom:env(safe-area-inset-bottom)"></div>',
+    };
+}
+export function createSafeAreaBridge(options) {
+    return createSafeAreaBridgeForRollouts(options, new Set(['sharedDefault']));
+}
+export function createReferenceSafeAreaBridge(options) {
+    return createSafeAreaBridgeForRollouts(options, new Set(['sharedDefault', 'referenceProduction']));
+}

package/dist/safe-area-profiles.d.ts

@@ -0,0 +1,50 @@
+export type SafeAreaCompatibilityProfile = {
+    id: string;
+    platform: 'ios' | 'android';
+    minimumRuntimeVersion: readonly [major: number, minor: number];
+    displayMode: 'standalone' | 'browser';
+    orientation: 'portrait' | 'landscape';
+    screen: {
+        width: number;
+        height: number;
+    };
+    devicePixelRatio: number;
+    reserve: {
+        bottom: number;
+    };
+    maturity: 'candidate' | 'provisional' | 'verified' | 'established';
+    rollout: 'probe' | 'referenceProduction' | 'consumerOptIn' | 'sharedDefault';
+};
+export declare const safeAreaCompatibilityProfiles: ({
+    id: string;
+    platform: "ios";
+    minimumRuntimeVersion: [number, number];
+    displayMode: "standalone";
+    orientation: "portrait";
+    screen: {
+        width: number;
+        height: number;
+    };
+    devicePixelRatio: number;
+    reserve: {
+        bottom: number;
+    };
+    maturity: "provisional";
+    rollout: "referenceProduction";
+} | {
+    id: string;
+    platform: "ios";
+    minimumRuntimeVersion: [number, number];
+    displayMode: "standalone";
+    orientation: "portrait";
+    screen: {
+        width: number;
+        height: number;
+    };
+    devicePixelRatio: number;
+    reserve: {
+        bottom: number;
+    };
+    maturity: "verified";
+    rollout: "referenceProduction";
+})[];

package/dist/safe-area-profiles.js

@@ -0,0 +1,57 @@
+// This private catalog is package-owned. The public root projects only
+// sharedDefault entries; the explicit reference subpath additionally projects
+// referenceProduction entries for the source application that supplied their
+// current evidence. Consumers do not select or redefine individual profiles.
+export const safeAreaCompatibilityProfiles = [
+    // Provisional entries come from the iOS 26.5 Simulator S2-S5 matrix recorded
+    // in Base's Document Shell platform-extraction plan. The verified reference
+    // entry additionally has repeated real-device video + trace evidence.
+    {
+        id: 'ios-375x812-3x-portrait-standalone',
+        platform: 'ios',
+        minimumRuntimeVersion: [26, 0],
+        displayMode: 'standalone',
+        orientation: 'portrait',
+        screen: { width: 375, height: 812 },
+        devicePixelRatio: 3,
+        reserve: { bottom: 34 },
+        maturity: 'provisional',
+        rollout: 'referenceProduction',
+    },
+    {
+        id: 'ios-393x852-3x-portrait-standalone',
+        platform: 'ios',
+        minimumRuntimeVersion: [26, 0],
+        displayMode: 'standalone',
+        orientation: 'portrait',
+        screen: { width: 393, height: 852 },
+        devicePixelRatio: 3,
+        reserve: { bottom: 34 },
+        maturity: 'provisional',
+        rollout: 'referenceProduction',
+    },
+    {
+        id: 'ios-402x874-3x-portrait-standalone',
+        platform: 'ios',
+        minimumRuntimeVersion: [26, 0],
+        displayMode: 'standalone',
+        orientation: 'portrait',
+        screen: { width: 402, height: 874 },
+        devicePixelRatio: 3,
+        reserve: { bottom: 34 },
+        maturity: 'verified',
+        rollout: 'referenceProduction',
+    },
+    {
+        id: 'ios-430x932-3x-portrait-standalone',
+        platform: 'ios',
+        minimumRuntimeVersion: [26, 0],
+        displayMode: 'standalone',
+        orientation: 'portrait',
+        screen: { width: 430, height: 932 },
+        devicePixelRatio: 3,
+        reserve: { bottom: 34 },
+        maturity: 'provisional',
+        rollout: 'referenceProduction',
+    },
+];

package/dist/vite.d.ts

@@ -0,0 +1,8 @@
+import type { Plugin } from 'vite';
+import { type DocumentShellBuildContext, type DocumentShellComposition } from './document-shell.ts';
+export type DocumentShellPluginOptions = {
+    render: (context: DocumentShellBuildContext) => DocumentShellComposition | Promise<DocumentShellComposition>;
+    validateFinalDocument?: (html: string, context: DocumentShellBuildContext) => void;
+    runtimeHandoff?: boolean;
+};
+export declare function documentShell(options: DocumentShellPluginOptions): Plugin[];

package/dist/vite.js

@@ -0,0 +1,86 @@
+import { Buffer } from 'node:buffer';
+import { compileDocumentShell, locateSingleStylesheetLink, validateCompiledDocumentShell, validateDocumentShellTemplate, validateRuntimeHandoffDocument, } from "./document-shell.js";
+import { documentShellRuntimeStylesheetId, } from "./client.js";
+function readIndexAsset(bundle) {
+    const indexAsset = Object.values(bundle).find((entry) => typeof entry === 'object' &&
+        entry !== null &&
+        'type' in entry &&
+        entry.type === 'asset' &&
+        'fileName' in entry &&
+        entry.fileName === 'index.html');
+    if (!indexAsset)
+        throw new Error('Document shell could not find emitted index.html');
+    return indexAsset;
+}
+function escapeHtmlAttribute(value) {
+    return value
+        .replaceAll('&', '&')
+        .replaceAll('"', '"')
+        .replaceAll('<', '&lt;')
+        .replaceAll('>', '&gt;');
+}
+function deferRuntimeStylesheet() {
+    return {
+        name: 'document-shell:defer-runtime-stylesheet',
+        apply: 'build',
+        enforce: 'post',
+        transformIndexHtml(html) {
+            const stylesheet = locateSingleStylesheetLink(html);
+            const href = stylesheet.attributes.href;
+            if (!href)
+                throw new Error('Emitted runtime stylesheet is missing an href');
+            const replacedAttributes = new Set(['id', 'rel', 'as', 'href', 'onload', 'onerror']);
+            const forwardedAttributes = Object.entries(stylesheet.attributes)
+                .filter(([name]) => !replacedAttributes.has(name))
+                .map(([name, value]) => value === '' ? ` ${name}` : ` ${name}="${escapeHtmlAttribute(value)}"`)
+                .join('');
+            const bootstrap = `<script data-document-shell-runtime-stylesheet="true">(()=>{const stylesheet=document.getElementById('${documentShellRuntimeStylesheetId}');if(!stylesheet)return;const emit=(state,detail)=>document.dispatchEvent(new CustomEvent('document-shell:runtime-stylesheet',{detail:{state,detail}}));const markFailure=(failure)=>{if(stylesheet.dataset.failure===failure)return;stylesheet.dataset.failure=failure;emit('failed',failure)};const deadline=Date.now()+3000;stylesheet.dataset.failureDeadline=String(deadline);const timer=window.setTimeout(()=>{if(stylesheet.dataset.loaded!=='true')markFailure('timeout')},Math.max(0,deadline-Date.now()));stylesheet.addEventListener('load',()=>{window.clearTimeout(timer);stylesheet.dataset.loaded='true';stylesheet.rel='stylesheet';emit('loaded')},{once:true});stylesheet.addEventListener('error',()=>{window.clearTimeout(timer);markFailure('error')},{once:true})})()</script>`;
+            const deferredLink = `<link id="${documentShellRuntimeStylesheetId}" rel="preload" as="style"${forwardedAttributes} href="${escapeHtmlAttribute(href)}">${bootstrap}`;
+            return `${html.slice(0, stylesheet.startOffset)}${deferredLink}${html.slice(stylesheet.endOffset)}`;
+        },
+    };
+}
+export function documentShell(options) {
+    let resolvedDocument;
+    let command = 'build';
+    let mode = 'production';
+    const producer = {
+        name: 'document-shell:compile',
+        enforce: 'pre',
+        configResolved(config) {
+            command = config.command;
+            mode = config.mode;
+        },
+        transformIndexHtml: {
+            order: 'pre',
+            async handler(template) {
+                const buildContext = { command, mode };
+                const composition = await options.render(buildContext);
+                validateDocumentShellTemplate(template, composition.document.appEntry);
+                resolvedDocument = composition.document;
+                return compileDocumentShell(composition);
+            },
+        },
+    };
+    const finalGate = {
+        name: 'document-shell:final-artifact-gate',
+        apply: 'build',
+        enforce: 'post',
+        generateBundle(_outputOptions, bundle) {
+            if (!resolvedDocument) {
+                throw new Error('Document shell final gate ran before the document compiler');
+            }
+            const indexAsset = readIndexAsset(bundle);
+            const html = typeof indexAsset.source === 'string'
+                ? indexAsset.source
+                : Buffer.from(indexAsset.source).toString('utf8');
+            validateCompiledDocumentShell(html, resolvedDocument, { transformedAppEntry: true });
+            if (options.runtimeHandoff)
+                validateRuntimeHandoffDocument(html);
+            options.validateFinalDocument?.(html, { command, mode });
+        },
+    };
+    return options.runtimeHandoff
+        ? [producer, deferRuntimeStylesheet(), finalGate]
+        : [producer, finalGate];
+}