@stacksjs/stx 0.2.152 → 0.2.153

package/dist/app-shell.js

@@ -114,9 +114,36 @@ ${routerScript}
 </body>
 </html>`;
 }
+function startsDocument(html) {
+  let i = 0;
+  while (i < html.length) {
+    const rest = html.slice(i), ws = rest.match(/^\s+/);
+    if (ws) {
+      i += ws[0].length;
+      continue;
+    }
+    if (rest.startsWith("<!--")) {
+      const end = html.indexOf("-->", i);
+      if (end === -1)
+        return !1;
+      i = end + 3;
+      continue;
+    }
+    const scriptOpen = rest.match(/^<script\b[^>]*>/i);
+    if (scriptOpen) {
+      const end = html.toLowerCase().indexOf("</script>", i + scriptOpen[0].length);
+      if (end === -1)
+        return !1;
+      i = end + 9;
+      continue;
+    }
+    return /^<!DOCTYPE\b/i.test(rest) || /^<html[\s>]/i.test(rest);
+  }
+  return !1;
+}
 export function stripDocumentWrapper(html, options = {}) {
   const trimmed = html.trim();
-  if (!/<!DOCTYPE\b/i.test(trimmed) && !/^<html[\s>]/i.test(trimmed))
+  if (!startsDocument(trimmed))
     return html;
   const headStyles = [], headMatch = trimmed.match(/<head\b[^>]*>([\s\S]*?)<\/head>/i);
   if (headMatch) {

package/dist/browser-composables.d.ts

@@ -1,6 +1,11 @@
 /**
  * Reactive localStorage with automatic serialization.
  *
+ * @deprecated Returns `{ value, remove }` — a third shape for this name, and
+ * one the signals runtime cannot see. Use `useLocalStorage` from
+ * `@stacksjs/stx`, which returns a Signal (`s()` reads, `s.set(v)` writes) on
+ * every import path (stacksjs/stx#1797).
+ *
  * @example
  * ```typescript
  * const theme = useLocalStorage('theme', 'dark')
@@ -12,6 +17,9 @@ export declare function useLocalStorage<T>(key: string, defaultValue: T): { valu
 /**
  * Reactive sessionStorage with automatic serialization.
  *
+ * @deprecated See {@link useLocalStorage} above — use the Signal-returning
+ * version from `@stacksjs/stx` (stacksjs/stx#1797).
+ *
  * @example
  * ```typescript
  * const token = useSessionStorage('auth_token', null)

package/dist/build-id.d.ts

@@ -0,0 +1,49 @@
+/**
+ * The current process's build id.
+ *
+ * Stable for the lifetime of the process, which is the unit that matters: a
+ * `bun --watch` restart produces a new process and therefore a new id, while a
+ * production build stamps every page it renders with one value.
+ *
+ * `STX_BUILD_ID` overrides it, for deployments that render across several
+ * processes and need them to agree.
+ */
+export declare function getBuildId(): string;
+/** @internal test-only — force the id, or with `null` restore generation. */
+export declare function __setBuildIdForTest(id: string | null): void;
+/**
+ * Add `<meta name="stx-build">` to `<head>` if it isn't already there.
+ *
+ * Idempotent, and a no-op for output with no `<head>` — SPA fragments carry the
+ * id in a response header instead, since they have nowhere to put a meta.
+ */
+export declare function injectBuildId(html: string, buildId?: string): string;
+/**
+ * Per-process build identity, used to detect runtime/fragment skew
+ * (stacksjs/stx#1772).
+ *
+ * Under `bun --watch`, a loaded page holds the client runtime from build N. A
+ * file save restarts the server, and the next SPA navigation fetches a fragment
+ * rendered by build N+1. Fragments legitimately carry preserved `{{ }}`
+ * moustaches for client-side binding, so any drift in the scoped-script or
+ * binding format between the two builds leaves the OLD runtime unable to
+ * hydrate the NEW fragment: literal moustaches on screen, dead `:show`, stale
+ * canvas. It is sporadic and never reproduces from a clean boot, which is
+ * exactly its signature.
+ *
+ * Stamping the identity on both sides lets the router notice the mismatch and
+ * fall back to a full page navigation — the same thing Next and Vite's HMR
+ * clients do on a version mismatch. It does not fix format drift; it makes the
+ * whole class of skew symptoms impossible to observe.
+ *
+ * The comparison is deliberately conservative: the router only acts when BOTH
+ * sides are known. A missing id means "no information", never "mismatch".
+ * That keeps statically hosted output (no headers to send) and any consumer on
+ * an older server working exactly as before.
+ *
+ * @module build-id
+ */
+/** `<meta name="stx-build">` on every rendered page. */
+export declare const BUILD_ID_META: 'stx-build';
+/** Response header carrying the id that rendered an SPA fragment. */
+export declare const BUILD_ID_HEADER: 'X-STX-Build';

package/dist/build-id.js

@@ -0,0 +1,20 @@
+export const BUILD_ID_META = "stx-build", BUILD_ID_HEADER = "X-STX-Build";
+let cached = null;
+export function getBuildId() {
+  if (cached === null)
+    cached = process.env.STX_BUILD_ID || `${Date.now().toString(36)}${Math.random().toString(36).slice(2, 8)}`;
+  return cached;
+}
+export function __setBuildIdForTest(id) {
+  cached = id;
+}
+export function injectBuildId(html, buildId = getBuildId()) {
+  if (html.includes(`name="${BUILD_ID_META}"`))
+    return html;
+  const headOpen = /<head\b[^>]*>/i.exec(html);
+  if (!headOpen)
+    return html;
+  const insertAt = headOpen.index + headOpen[0].length;
+  return `${html.slice(0, insertAt)}
+  <meta name="${BUILD_ID_META}" content="${buildId}">${html.slice(insertAt)}`;
+}