@ohos-ports/stacksjs-stx 0.2.287-beta.0

package/dist/fragment-container.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Parse the supported subset of CSS selector syntax.
+ *
+ * Returns null for anything unsupported (descendant combinators, `:has()`,
+ * comma lists) rather than guessing — a wrong container is worse than a
+ * reported one.
+ */
+export declare function parseContainerSelector(selector: string): ParsedSelector | null;
+/**
+ * Find the region of `html` occupied by the first element matching `selector`.
+ *
+ * The closing tag is found by depth counting over same-named tags, so a
+ * container that contains another element of the same name — or a page that has
+ * two of them — resolves to the container's OWN close rather than the last one
+ * in the document.
+ */
+export declare function findContainerRegion(html: string, selector?: string): ContainerRegion | null;
+/**
+ * Locating the SPA swap container in rendered HTML.
+ *
+ * The client resolves the container with a CSS selector (`router.container`,
+ * falling back to `[data-stx-content]` then `main`). The server used to ignore
+ * that entirely and string-slice from the first `<main …>` to the LAST
+ * `</main>`, which produced three separate failures:
+ *
+ *  - configuring `router: { container: '[data-stx-content]' }` still produced a
+ *    `<main>`-shaped fragment, which the client then injected into a different
+ *    element, duplicating the page chrome;
+ *  - a page with two `<main>` elements swapped everything between the first open
+ *    and the last close, i.e. the wrong span;
+ *  - a page with no `<main>` shipped its whole body as the "fragment", silently
+ *    disabling SPA navigation for every link on it, at HTTP 200.
+ *
+ * This module resolves the same selector the client uses and finds the container's
+ * OWN matching close tag by depth counting, so nesting and repetition behave.
+ *
+ * It is deliberately a small matcher, not a CSS engine: it covers the selector
+ * shapes a swap container realistically uses — a tag name, an attribute, an id,
+ * a class, and a tag qualified by one of those. Anything else returns null, and
+ * the caller is expected to say so rather than silently ship the whole body.
+ *
+ * @module fragment-container
+ */
+export declare interface ContainerRegion {
+  openTag: string
+  openIndex: number
+  start: number
+  end: number
+  tagName: string
+}
+declare interface ParsedSelector {
+  tag?: string
+  attr?: string
+  attrValue?: string
+  id?: string
+  className?: string
+}

package/dist/fragment-container.js

@@ -0,0 +1,123 @@
+const VOID_ELEMENTS = new Set([
+  "area",
+  "base",
+  "br",
+  "col",
+  "embed",
+  "hr",
+  "img",
+  "input",
+  "link",
+  "meta",
+  "param",
+  "source",
+  "track",
+  "wbr"
+]);
+function ignoredMarkupRanges(html) {
+  const ranges = [], ignoredRe = /<!--[\s\S]*?(?:-->|$)|<(script|style|textarea|title|template)\b[^>]*>[\s\S]*?<\/\1\s*>/gi;
+  let match;
+  while ((match = ignoredRe.exec(html)) !== null)
+    ranges.push({ start: match.index, end: match.index + match[0].length });
+  return ranges;
+}
+function isIgnoredOffset(offset, ranges) {
+  return ranges.some((range) => offset >= range.start && offset < range.end);
+}
+export function parseContainerSelector(selector) {
+  const trimmed = (selector || "").trim();
+  if (!trimmed)
+    return null;
+  if (/[\s>+~,:]/.test(trimmed))
+    return null;
+  const parsed = {};
+  let rest = trimmed;
+  const tagMatch = rest.match(/^[a-z][\w-]*/i);
+  if (tagMatch) {
+    parsed.tag = tagMatch[0].toLowerCase();
+    rest = rest.slice(tagMatch[0].length);
+  }
+  while (rest.length > 0) {
+    const attr = rest.match(/^\[([\w-]+)(?:=(["']?)([^\]"']*)\2)?\]/);
+    if (attr) {
+      parsed.attr = attr[1];
+      if (attr[3] !== void 0 && attr[3] !== "")
+        parsed.attrValue = attr[3];
+      rest = rest.slice(attr[0].length);
+      continue;
+    }
+    const id = rest.match(/^#([\w-]+)/);
+    if (id) {
+      parsed.id = id[1];
+      rest = rest.slice(id[0].length);
+      continue;
+    }
+    const cls = rest.match(/^\.([\w-]+)/);
+    if (cls) {
+      parsed.className = cls[1];
+      rest = rest.slice(cls[0].length);
+      continue;
+    }
+    return null;
+  }
+  if (!parsed.tag && !parsed.attr && !parsed.id && !parsed.className)
+    return null;
+  return parsed;
+}
+function attributesMatch(attrs, parsed) {
+  if (parsed.attr) {
+    if (!(parsed.attrValue === void 0 ? new RegExp(`\\b${parsed.attr}(?=[\\s=>/]|$)`, "i") : new RegExp(`\\b${parsed.attr}\\s*=\\s*(["'])\\s*${parsed.attrValue}\\s*\\1`, "i")).test(attrs))
+      return !1;
+  }
+  if (parsed.id) {
+    if (!new RegExp(`\\bid\\s*=\\s*(["'])\\s*${parsed.id}\\s*\\1`, "i").test(attrs))
+      return !1;
+  }
+  if (parsed.className) {
+    const classMatch = attrs.match(/\bclass\s*=\s*(["'])([\s\S]*?)\1/i);
+    if (!classMatch)
+      return !1;
+    if (!classMatch[2].split(/\s+/).includes(parsed.className))
+      return !1;
+  }
+  return !0;
+}
+export function findContainerRegion(html, selector = "main") {
+  const parsed = parseContainerSelector(selector);
+  if (!parsed)
+    return null;
+  const openRe = /<([a-z][\w-]*)\b([^>]*)>/gi, ignoredRanges = ignoredMarkupRanges(html);
+  let match;
+  while ((match = openRe.exec(html)) !== null) {
+    if (isIgnoredOffset(match.index, ignoredRanges))
+      continue;
+    const tagName = match[1].toLowerCase(), attrs = match[2] || "";
+    if (attrs.trimEnd().endsWith("/") || VOID_ELEMENTS.has(tagName))
+      continue;
+    if (parsed.tag && parsed.tag !== tagName)
+      continue;
+    if (!attributesMatch(attrs, parsed))
+      continue;
+    const openTag = match[0], contentStart = match.index + openTag.length, pairRe = new RegExp(`<(/?)${tagName}\\b([^>]*)>`, "gi");
+    pairRe.lastIndex = contentStart;
+    let depth = 1, pair;
+    while ((pair = pairRe.exec(html)) !== null) {
+      if (isIgnoredOffset(pair.index, ignoredRanges))
+        continue;
+      const isClose = pair[1] === "/";
+      if (!isClose && (pair[2] || "").trimEnd().endsWith("/"))
+        continue;
+      depth += isClose ? -1 : 1;
+      if (depth === 0)
+        return {
+          openTag,
+          openIndex: match.index,
+          start: contentStart,
+          end: pair.index,
+          tagName
+        };
+    }
+    return null;
+  }
+  return null;
+}

package/dist/framework-composables.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Ship the framework's own browser-only composables to the client
+ * (stacksjs/stx#1805).
+ *
+ * `src/composables/` exports 149 functions; 120 of them have no counterpart in
+ * the client runtime. They are exported from the package, they type-check, they
+ * autocomplete — and they are unreachable from the only environment where their
+ * underlying API exists. `useClipboard`, `useGeolocation`, `useFullscreen`,
+ * `useBattery` and the observer family all wrap browser APIs and all threw
+ * `ReferenceError` when called from a `<script client>` block.
+ *
+ * There are two ways to close that gap. Hand-porting each one into the runtime's
+ * template literal duplicates 120 implementations that already exist and would
+ * drift the same way the auto-import list did (#1804). Instead this bundles the
+ * real modules — one source of truth — and merges them onto `window.stx`.
+ *
+ * DEMAND-DRIVEN: only composables the page actually references are emitted, so
+ * a page calling `useClipboard` ships a couple of KB rather than the whole tree.
+ *
+ * SKIP, NEVER CLOBBER: a name the runtime already provides wins. The runtime
+ * versions are the signal-based ones that #1710/#1726/#1797 unified; replacing
+ * them with the module versions would be a regression, not a fix.
+ *
+ * KNOWN LIMITATION, and it is why this is a bridge rather than the end state:
+ * these are pre-unification shapes — a getter plus `subscribe()` plus a manual
+ * `stop()`, not signals. So `useClipboard().copy(text)` works, `subscribe()`
+ * works, and imperative use is correct; but reading `.copied` in a template does
+ * not re-render on its own. Converting them to the Signal contract is the real
+ * fix and is tracked separately.
+ *
+ * @module framework-composables
+ */
+/** Clear the cache. Dev HMR calls this when composables change on disk. */
+export declare function clearFrameworkComposableCache(): void;
+/**
+ * Choose which files in the composables directory carry runtime code.
+ *
+ * This ran against a `*.ts` glob, which is only ever right when stx runs from
+ * `src/`. A released package runs from `dist/`, where the directory holds 37
+ * `.js` files and 37 `.d.ts` files and not one plain `.ts` — so every file the
+ * bundler opened was type-only, nothing was ever emitted, and every requested
+ * name was reported as unbundlable. The one configuration where the old glob
+ * worked is the one the repo's own tests run in, which is why it never showed
+ * up here (stacksjs/stx#1832).
+ *
+ * Two compounding details, both fixed by going through this function:
+ *
+ *  - `.d.ts` can never contribute runtime code, so it is excluded outright
+ *    rather than left to be caught downstream.
+ *  - The barrel exclusion compared `endsWith('index.ts')`, and `'index.d.ts'`
+ *    does not end with that. The one file the filter existed to skip was the
+ *    only one it let through — and being a barrel of `export … from …`, it was
+ *    also the one shape the export-stripping below cannot parse.
+ *
+ * Exported so the selection can be tested against a dist-shaped listing without
+ * a built package.
+ */
+export declare function selectComposableFiles(files: string[]): string[];
+/**
+ * Which framework composables does this source actually call?
+ *
+ * Restricted to the server-only set, so a page calling `useLocalStorage` (which
+ * the runtime provides) never drags in a module copy.
+ */
+export declare function referencedFrameworkComposables(source: string): string[];
+/**
+ * Build a script exposing `names` on `window.stx` and as bare globals.
+ *
+ * Returns null when nothing is needed.
+ */
+export declare function getFrameworkComposableScript(source: string, composablesDir?: string): Promise<string | null>;
+/** @internal test-only — declare names the runtime provides. */
+export declare function __setRuntimeOwnedForTest(names: string[]): void;

package/dist/framework-composables.js

@@ -0,0 +1,126 @@
+import path from "node:path";
+import { getPublicEnvDefine } from "./public-env.js";
+import { SERVER_ONLY_COMPOSABLES } from "./unresolved-identifiers.js";
+import { getSharedTranspiler } from "./utils.js";
+import { contentKey, renderMemo } from "./render-memo.js";
+const _cache = new Map, referenced = renderMemo(64), RUNTIME_OWNED = new Set;
+let runtimeOwnedGeneration = 0;
+const SERVER_ONLY = new Set(SERVER_ONLY_COMPOSABLES);
+export function clearFrameworkComposableCache() {
+  _cache.clear();
+  referenced.clear();
+}
+export function selectComposableFiles(files) {
+  const byBase = new Map;
+  for (const file of files) {
+    const base = path.basename(file);
+    if (base.endsWith(".d.ts"))
+      continue;
+    const stem = base.replace(/\.[jt]s$/, "");
+    if (stem === "index")
+      continue;
+    if (stem === base)
+      continue;
+    const existing = byBase.get(stem);
+    if (existing && !existing.endsWith(".js"))
+      continue;
+    byBase.set(stem, file);
+  }
+  return [...byBase.values()].sort();
+}
+function declaresLocally(source, name) {
+  const escaped = name.replace(/[$()*+.?[\\\]^{|}-]/g, "\\$&");
+  return new RegExp(`(?:^|[^\\w$.])(?:const|let|var|function|class)\\s+${escaped}\\b`).test(source);
+}
+export function referencedFrameworkComposables(source) {
+  if (!source)
+    return [];
+  const key = contentKey(source, runtimeOwnedGeneration), remembered = referenced.get(key);
+  if (remembered)
+    return remembered.slice();
+  const authored = source.replace(/<script\b[^>]*\bdata-stx-runtime\b[^>]*>[\s\S]*?<\/script>/gi, "").replace(/<script\b[^>]*\bdata-stx-framework-composables\b[^>]*>[\s\S]*?<\/script>/gi, "").replace(/<script\b[^>]*\bdata-stx-stores\b[^>]*>[\s\S]*?<\/script>/gi, "").replace(/<script\b[^>]*\bdata-stx-composables\b[^>]*>[\s\S]*?<\/script>/gi, ""), found = [];
+  for (const name of SERVER_ONLY) {
+    if (RUNTIME_OWNED.has(name))
+      continue;
+    const escaped = name.replace(/[$()*+.?[\\\]^{|}-]/g, "\\$&");
+    if (new RegExp(`(^|[^\\w$.])${escaped}\\s*\\(`).test(authored))
+      found.push(name);
+  }
+  found.sort();
+  referenced.set(key, found);
+  return found.slice();
+}
+export async function getFrameworkComposableScript(source, composablesDir) {
+  const names = referencedFrameworkComposables(source);
+  if (names.length === 0)
+    return null;
+  const dir = composablesDir ?? path.join(import.meta.dir, "composables"), key = `${dir}\x00${names.join(",")}`, cached = _cache.get(key);
+  if (cached !== void 0)
+    return cached || null;
+  const transpiler = getSharedTranspiler({ loader: "ts", target: "browser", define: getPublicEnvDefine() }), wanted = new Set(names), chunks = [], emitted = new Set;
+  let files = [];
+  try {
+    const glob = new Bun.Glob("*.{ts,js}");
+    for await (const file of glob.scan({ cwd: dir, absolute: !0 }))
+      files.push(file);
+  } catch {
+    _cache.set(key, "");
+    return null;
+  }
+  files = selectComposableFiles(files);
+  for (const file of files) {
+    let code;
+    try {
+      code = await Bun.file(file).text();
+    } catch {
+      continue;
+    }
+    let exports = [];
+    try {
+      exports = transpiler.scan(code).exports.filter((n) => n !== "default");
+    } catch {
+      continue;
+    }
+    if (!exports.some((n) => wanted.has(n)))
+      continue;
+    try {
+      code = code.replace(/^import\s+.*from\s+['"][^'"]+['"]\s*;?\s*$/gm, "");
+      code = code.replace(/^import\s+type\s+.*$/gm, "");
+      code = code.replace(/^export\s+\*\s+(?:as\s+\w+\s+)?from\s*['"][^'"]+['"]\s*;?\s*$/gm, "");
+      code = code.replace(/^export\s+(?:type\s+)?\{[\s\S]*?\}\s*(?:from\s*['"][^'"]+['"]\s*)?;?\s*$/gm, "");
+      code = code.replace(/^export\s+default\s+/gm, "");
+      code = code.replace(/^export\s+(?=(?:declare\s+)?(?:abstract\s+)?(?:async\s+)?(?:function|class|const|let|var|type|interface|enum)\b)/gm, "");
+      chunks.push(`// ${path.basename(file).replace(/\.[jt]s$/, "")}
+${transpiler.transformSync(code).trim()}`);
+      for (const name of exports)
+        emitted.add(name);
+    } catch (error) {
+      console.warn(`[stx] framework composable ${path.basename(file)} could not be bundled:`, error);
+    }
+  }
+  const missing = names.filter((n) => !emitted.has(n) && !declaresLocally(source, n));
+  if (missing.length > 0)
+    console.warn(`[stx] could not bundle ${missing.join(", ")} from @stacksjs/stx/composables \u2014 ` + "calls to them will throw ReferenceError in the browser. Import them explicitly so the bundler inlines them, or use a runtime equivalent from window.stx.");
+  if (chunks.length === 0) {
+    _cache.set(key, "");
+    return null;
+  }
+  const assignments = [...emitted].map((name) => `  try { if (!(${JSON.stringify(name)} in __s)) { __s[${JSON.stringify(name)}] = ${name}; if (!(${JSON.stringify(name)} in window)) window[${JSON.stringify(name)}] = ${name}; } } catch (e) {}`).join(`
+`), script = `<script data-stx-framework-composables>
+;(function(){
+  var __s = window.stx = window.stx || {};
+${chunks.join(`
+
+`)}
+${assignments}
+})();
+</script>`;
+  _cache.set(key, script);
+  return script;
+}
+export function __setRuntimeOwnedForTest(names) {
+  RUNTIME_OWNED.clear();
+  for (const n of names)
+    RUNTIME_OWNED.add(n);
+  runtimeOwnedGeneration++;
+}

package/dist/head-injection.d.ts

@@ -0,0 +1,61 @@
+/**
+ * One splice into `<head>` instead of one per thing being injected
+ * (stacksjs/stx#1945).
+ *
+ * Several passes each add a small fragment to the head of a finished page: the
+ * x-cloak style, the color-mode boot script, the build-id meta. Each was
+ * written the obvious way -- find the anchor, return
+ * `slice(0, i) + fragment + slice(i)` -- and each of those returns a NEW copy
+ * of the whole document. On a 212KB page that is 212KB allocated to insert a
+ * few hundred bytes, three times over, and the measured cost of the top-level
+ * pipeline was dominated by exactly this shape: of 86 assignments in a render,
+ * only ten produced a new string, and six of them were whole-document copies
+ * made to insert something small.
+ *
+ * A pass that contributes a fragment instead of splicing it lets all of them
+ * share one rebuild. Order is preserved within each anchor, which is the part
+ * that matters: the boot script has to precede the cloak style in the head, and
+ * both have to be live before first paint.
+ *
+ * Nothing here decides WHETHER a fragment applies. Each caller keeps its own
+ * guard -- idempotence checks, config gates -- and simply contributes nothing
+ * when it does not apply, so a page that needs no injections is not rebuilt.
+ *
+ * @module head-injection
+ */
+/** Fragments waiting to be spliced into one document. */
+export interface HeadInjections {
+    /** Inserted immediately after the `<head ...>` open tag, in push order. */
+    afterOpen: string[];
+    /** Inserted immediately before `</head>`, in push order. */
+    beforeClose: string[];
+}
+export declare function createHeadInjections(): HeadInjections;
+/** Whether anything was contributed, so a caller can skip the rebuild entirely. */
+export declare function hasHeadInjections(injections: HeadInjections): boolean;
+/**
+ * Apply every collected fragment in a single pass.
+ *
+ * Returns `html` untouched -- the same reference, not a copy -- when there is
+ * nothing to add or the document has no head to add it to. A page without a
+ * `<head>` is not an error here: SPA fragments have nowhere to put these and
+ * are served with the same information in response headers instead.
+ */
+export declare function applyHeadInjections(html: string, injections: HeadInjections): string;
+/**
+ * Offset of the canonical head-injection position: just inside `<head>`, after
+ * a `<meta charset>` that leads it. `null` when the document has no head.
+ *
+ * Stepping over the charset is not cosmetic. The encoding declaration has to
+ * land inside the document's first 1024 bytes, and what gets inserted here is
+ * big enough to push it out -- the signals runtime is the whole client library,
+ * the default SEO block ~500 bytes. Displacing it was then repaired at the end
+ * of the pipeline by hoisting the charset back up, which rebuilt the whole
+ * document (186KB on a 199KB page) to move three bytes. Every injector landing
+ * after the charset means the order is right the first time and there is
+ * nothing to repair (stacksjs/stx#1945).
+ *
+ * `hoistCharsetMeta` stays as the backstop for anything that does not come
+ * through here.
+ */
+export declare function headInsertionPoint(html: string): number | null;

package/dist/head-injection.js

@@ -0,0 +1,28 @@
+export function createHeadInjections() {
+  return { afterOpen: [], beforeClose: [] };
+}
+export function hasHeadInjections(injections) {
+  return injections.afterOpen.length > 0 || injections.beforeClose.length > 0;
+}
+export function applyHeadInjections(html, injections) {
+  if (!hasHeadInjections(injections))
+    return html;
+  const afterOpen = injections.afterOpen.join(""), beforeClose = injections.beforeClose.join(""), headCloseIdx = html.lastIndexOf("</head>"), openAt = afterOpen ? headInsertionPoint(html) : null, closeAt = beforeClose && headCloseIdx !== -1 ? headCloseIdx : null;
+  if (openAt === null && closeAt === null)
+    return html;
+  if (openAt !== null && closeAt !== null)
+    return `${html.slice(0, openAt)}${afterOpen}${html.slice(openAt, closeAt)}${beforeClose}${html.slice(closeAt)}`;
+  if (openAt !== null)
+    return `${html.slice(0, openAt)}${afterOpen}${html.slice(openAt)}`;
+  return `${html.slice(0, closeAt)}${beforeClose}${html.slice(closeAt)}`;
+}
+const LEADING_CHARSET_META = /\s*<meta\b[^>]*\bcharset\b[^>]*>/iy;
+export function headInsertionPoint(html) {
+  const headOpen = /<head\b[^>]*>/i.exec(html);
+  if (!headOpen)
+    return null;
+  const afterTag = headOpen.index + headOpen[0].length;
+  LEADING_CHARSET_META.lastIndex = afterTag;
+  const charset = LEADING_CHARSET_META.exec(html);
+  return charset ? afterTag + charset[0].length : afterTag;
+}