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

package/dist/screenshot.d.ts

@@ -0,0 +1,22 @@
+/** Capture a single page to `output` using Bun's headless WebView. */
+export declare function captureScreenshot(input: string, output: string, opts?: ScreenshotOptions): Promise<ShotResult>;
+/**
+ * Capture `input` — a file, URL, or directory of `*.html` — to PNG(s) in
+ * `outDir`. Returns one result per page.
+ */
+export declare function captureScreenshots(input: string, outDir: string, opts?: ScreenshotOptions): Promise<ShotResult[]>;
+export declare interface ScreenshotOptions {
+  width?: number
+  height?: number
+  waitMs?: number
+  timeoutMs?: number
+  format?: 'png' | 'jpeg' | 'webp'
+  backend?: 'webkit' | 'chrome'
+  fullPage?: boolean
+  waitSelector?: string
+}
+export declare interface ShotResult {
+  input: string
+  output: string
+  bytes: number
+}

package/dist/screenshot.js

@@ -0,0 +1,100 @@
+import { WebView, default as Bun } from "./bun-shim.js";
+import { existsSync, mkdirSync, readdirSync, statSync } from "node:fs";
+import path from "node:path";
+const MAX_DIMENSION = 16384;
+function toUrl(input) {
+  if (/^https?:\/\//.test(input) || input.startsWith("file://"))
+    return input;
+  return `file://${path.resolve(input)}`;
+}
+function navigateAndWait(view, url, waitMs, timeoutMs) {
+  return new Promise((resolve) => {
+    let settled = !1, settleTimer, timeoutTimer;
+    const finish = () => {
+      if (!settled) {
+        settled = !0;
+        clearTimeout(timeoutTimer);
+        if (settleTimer)
+          clearTimeout(settleTimer);
+        view.onNavigated = void 0;
+        resolve();
+      }
+    };
+    timeoutTimer = setTimeout(finish, timeoutMs);
+    view.onNavigated = () => {
+      if (!settled)
+        settleTimer = setTimeout(finish, waitMs);
+    };
+    try {
+      const navigation = view.navigate(url);
+      if (navigation && typeof navigation.catch === "function")
+        navigation.catch(finish);
+    } catch {
+      finish();
+    }
+  });
+}
+async function waitForSelector(view, selector, timeoutMs) {
+  const expr = `!!document.querySelector(${JSON.stringify(selector)})`, deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    try {
+      if (await view.evaluate(expr))
+        return;
+    } catch {}
+    await new Promise((r) => setTimeout(r, 100));
+  }
+}
+async function measureFullHeight(view) {
+  try {
+    const h = await view.evaluate("Math.ceil(Math.max(document.documentElement.scrollHeight, document.documentElement.offsetHeight, document.body ? document.body.scrollHeight : 0, document.body ? document.body.offsetHeight : 0))");
+    return typeof h === "number" && Number.isFinite(h) && h > 0 ? Math.min(h, MAX_DIMENSION) : 0;
+  } catch {
+    return 0;
+  }
+}
+export async function captureScreenshot(input, output, opts = {}) {
+  const width = Math.min(opts.width ?? 1440, MAX_DIMENSION), height = Math.min(opts.height ?? 2200, MAX_DIMENSION), waitMs = opts.waitMs ?? 800, timeoutMs = opts.timeoutMs ?? 15000, format = opts.format ?? "png", url = toUrl(input), open = (h) => new WebView({
+    width,
+    height: h,
+    headless: !0,
+    ...opts.backend ? { backend: opts.backend } : {}
+  });
+  let view = open(height);
+  try {
+    await navigateAndWait(view, url, waitMs, timeoutMs);
+    if (opts.waitSelector)
+      await waitForSelector(view, opts.waitSelector, timeoutMs);
+    if (opts.fullPage) {
+      const full = await measureFullHeight(view);
+      if (full > height) {
+        view.close();
+        view = open(full);
+        await navigateAndWait(view, url, waitMs, timeoutMs);
+        if (opts.waitSelector)
+          await waitForSelector(view, opts.waitSelector, timeoutMs);
+      }
+    }
+    const buf = await view.screenshot({ encoding: "buffer", format });
+    mkdirSync(path.dirname(path.resolve(output)), { recursive: !0 });
+    await Bun.write(output, buf);
+  } finally {
+    view.close();
+  }
+  if (!existsSync(output))
+    throw Error(`Screenshot was not produced for ${input}`);
+  return { input, output, bytes: statSync(output).size };
+}
+export async function captureScreenshots(input, outDir, opts = {}) {
+  mkdirSync(outDir, { recursive: !0 });
+  let pages;
+  if (!/^https?:\/\//.test(input) && existsSync(input) && statSync(input).isDirectory())
+    pages = readdirSync(input).filter((f) => f.endsWith(".html")).map((f) => path.join(input, f));
+  else
+    pages = [input];
+  const ext = opts.format ?? "png", results = [];
+  for (const page of pages) {
+    const name = /^https?:\/\//.test(page) ? new URL(page).pathname.replace(/\W+/g, "-").replace(/^-|-$/g, "") || "index" : path.basename(page).replace(/\.html?$/, "");
+    results.push(await captureScreenshot(page, path.join(outDir, `${name}.${ext}`), opts));
+  }
+  return results;
+}

package/dist/script-classifier.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Classify a `<script>` tag as signals, client, or server.
+ *
+ * Classification rules (in priority order):
+ * 1. Explicit `server` attribute → server
+ * 2. Uses signals API (state, derived, effect, etc.) → signals
+ * 3. Has `client` attribute, `type="module"`, or `src=` → client
+ * 4. Everything else → server (executed at build time for variable extraction)
+ */
+export declare function classifyScript(attrs: string, content: string, fullTag: string): ScriptClassification;
+/**
+ * Classify all `<script>` tags in a template.
+ *
+ * The scan walks the template rather than running a global regex so that HTML
+ * comments are inert. A comment whose prose merely mentions a script tag — e.g.
+ * `<!-- the <script server> block owner-scopes the switcher -->` — used to be
+ * matched as a REAL opening tag, and the non-greedy regex then ran on to the
+ * next `</script>`. The resulting bogus `fullTag` spanned from inside the comment
+ * to the end of an unrelated script, so callers that delete `fullTag`
+ * (app-shell's `cleanTemplate`, serve-app's `templateContent`) erased the
+ * comment's `-->` terminator AND every real script in between — producing a
+ * runaway comment node that swallowed the rest of the document.
+ *
+ * `<template>` contents are deliberately still scanned: stx SFC files wrap their
+ * whole markup in `<template>`, and callers rely on scripts authored inside it
+ * being classified so they can be stripped from the rendered output.
+ *
+ * Returns arrays of scripts grouped by type.
+ */
+export declare function classifyAllScripts(content: string): {
+  signals: ScriptClassification[]
+  client: ScriptClassification[]
+  server: ScriptClassification[]
+};
+export declare interface ScriptClassification {
+  type: ScriptType
+  fullTag: string
+  content: string
+  attrs: string
+}
+export type ScriptType = 'signals' | 'client' | 'server';

package/dist/script-classifier.js

@@ -0,0 +1,51 @@
+import { matchHtmlComment, matchScriptElement } from "./html-masking.js";
+const SIGNALS_PATTERN = /\b(?:state|derived|effect|batch|ref|reactive|computed|watch|watchEffect)\s*(?:<[^>]*>)?\s*\(/;
+export function classifyScript(attrs, content, fullTag) {
+  const result = { fullTag, content, attrs };
+  if (/\bserver\b/.test(attrs))
+    return { ...result, type: "server" };
+  if (/\bdata-stx-scoped\b/.test(attrs))
+    return { ...result, type: "client" };
+  if (SIGNALS_PATTERN.test(content))
+    return { ...result, type: "signals" };
+  if (/\bclient\b/.test(attrs) || /\btype\s*=\s*["']module["']/.test(attrs) || /\bsrc\s*=/.test(attrs))
+    return { ...result, type: "client" };
+  return { ...result, type: "server" };
+}
+const SCRIPT_PARTS = /^<script\b([^>]*)>([\s\S]*)<\/script\s*>$/i;
+export function classifyAllScripts(content) {
+  const signals = [], client = [], server = [];
+  let i = 0;
+  while (i < content.length) {
+    const lt = content.indexOf("<", i);
+    if (lt === -1)
+      break;
+    const commentEnd = matchHtmlComment(content, lt);
+    if (commentEnd > lt) {
+      i = commentEnd;
+      continue;
+    }
+    const scriptEnd = matchScriptElement(content, lt);
+    if (scriptEnd > lt) {
+      const fullTag = content.slice(lt, scriptEnd), parts = SCRIPT_PARTS.exec(fullTag);
+      if (parts) {
+        const classification = classifyScript(parts[1], parts[2], fullTag);
+        switch (classification.type) {
+          case "signals":
+            signals.push(classification);
+            break;
+          case "client":
+            client.push(classification);
+            break;
+          case "server":
+            server.push(classification);
+            break;
+        }
+      }
+      i = scriptEnd;
+      continue;
+    }
+    i = lt + (content.startsWith("<!--", lt) ? 4 : 1);
+  }
+  return { signals, client, server };
+}

package/dist/script-emit.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Escape script bodies at EMIT time (stacksjs/stx#1792, part one item 2).
+ *
+ * A `</script>` anywhere inside a script body — in a string, a comment, or a
+ * runtime value — ends the element as far as the HTML parser is concerned. The
+ * rest of the script is then painted onto the page as text, and everything
+ * defined below the offending line silently does not exist.
+ *
+ * The documented workaround is to write `<\/script>` in the source. It does not
+ * work, and that is the crux of the report: `transpileTypeScript` runs every
+ * non-server block through Bun's transpiler, which NORMALISES the escape away
+ * before the browser ever sees it.
+ *
+ *   in : const s = "<\/script>"
+ *   out: const s = "</script>";
+ *
+ * So the escape protects the source from stx's own scanners and is then
+ * stripped, leaving the HTML parser to apply exactly the rule it was meant to
+ * dodge. Escaping on emit is the only place the protection can survive, because
+ * it happens after the transpiler.
+ *
+ * The transform is semantically inert for JavaScript: `\/` inside a string, a
+ * template literal, a regex literal or a comment parses as `/`. It is also
+ * valid inside JSON, where `\/` is an explicit escape — so a JSON-LD or
+ * importmap body would survive it, though those bodies are excluded upstream
+ * and never reach here.
+ *
+ * This is a leaf module on purpose: no stx imports, so every emit site can use
+ * it without creating a cycle.
+ */
+/**
+ * Neutralise closing script tags in a JavaScript body about to be embedded in
+ * an HTML `<script>` element.
+ *
+ * Idempotent: an already-escaped `<\/script` contains no `</script`, so
+ * re-running this is a no-op rather than a double-escape.
+ */
+export declare function escapeScriptBody(js: string): string;
+/**
+ * Warn when a body still carries a raw closing tag at emit time.
+ *
+ * A truncated script is never the intent, so this is worth saying out loud —
+ * both of the reported production incidents were diagnosed from the browser's
+ * "Unexpected end of input" rather than from anything stx said.
+ *
+ * Deliberately a warning rather than the `StxSyntaxError` the issue proposes: a
+ * hard throw here could brick a production build over a vendor bundle inlined
+ * through `stx-inline`, which is a worse failure than the one being reported.
+ */
+export declare function assertNoRawClose(js: string, site: string, filePath?: string): void;

package/dist/script-emit.js

@@ -0,0 +1,11 @@
+const RAW_CLOSE = /<\/(script)/gi;
+export function escapeScriptBody(js) {
+  if (!js || js.indexOf("</") === -1)
+    return js;
+  return js.replace(RAW_CLOSE, "<\\/$1");
+}
+export function assertNoRawClose(js, site, filePath) {
+  if (!js || !/<\/script/i.test(js))
+    return;
+  console.warn(`[stx] ${filePath ? `${filePath}: ` : ""}a script body emitted by ${site} still contains a literal closing script tag. The HTML parser will end the element there, so everything after it becomes page text and every declaration below it silently disappears. See stacksjs/stx#1792.`);
+}

package/dist/script-json.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Embed JSON inside a `<script>` tag safely.
+ *
+ * `JSON.stringify` alone is not enough for script content, in two ways that both
+ * end with the browser parsing something the author did not write:
+ *
+ *  - A `</script>` sequence inside any string value closes the tag early. The
+ *    rest of the JSON then lands in the document as markup, so whoever controls
+ *    that string controls the page.
+ *  - U+2028 and U+2029 are literal line terminators in JavaScript, though legal
+ *    unescaped in JSON. A value containing one splits the statement it sits in.
+ *
+ * This existed as five separate private copies — `spa-shell.ts`,
+ * `appearance-bootstrap.ts`, `color-mode-boot.ts`, `misc-directives.ts` and
+ * `bun-plugin/src/serve.ts`. That is the shape of bug this repo keeps paying
+ * for: a sixth injection site (`runtime-injection.ts`, added with the
+ * `ownedRoutes` table in #1864) had no escaping at all, because nothing
+ * connected it to the others.
+ *
+ * The escapes below are written as `\u` sequences rather than literal
+ * characters, and that is load-bearing. Writing a raw U+2028 inside the regex
+ * terminates the line mid-literal and the file stops parsing — this module's
+ * own first draft did exactly that, which is a fair demonstration of why the
+ * function needs to exist.
+ *
+ * @module script-json
+ */
+/**
+ * Escape an already-serialised JSON string for inclusion in a `<script>` body.
+ *
+ * `<` and `>` are escaped rather than only the `</script>` sequence, so no
+ * variant spelling (`</SCRIPT`, `</script foo`) can slip through.
+ */
+export declare function escapeJsonForScript(json: string): string;
+/** Serialise a value and escape it for a `<script>` body in one step. */
+export declare function toScriptJson(value: unknown): string;

package/dist/script-json.js

@@ -0,0 +1,6 @@
+export function escapeJsonForScript(json) {
+  return json.replace(/</g, "\\u003c").replace(/>/g, "\\u003e").replace(/\u2028/g, "\\u2028").replace(/\u2029/g, "\\u2029");
+}
+export function toScriptJson(value) {
+  return escapeJsonForScript(JSON.stringify(value));
+}

package/dist/script-validation.d.ts

@@ -0,0 +1,26 @@
+import type { StrictModeConfig } from './types';
+/**
+ * Prohibited DOM API patterns in client scripts.
+ * STX provides Vue-style alternatives via the STX global object.
+ */
+export declare const PROHIBITED_DOM_PATTERNS: Array<{
+    pattern: RegExp;
+    message: string;
+    suggestion: string;
+}>;
+/**
+ * Validate client script content for prohibited DOM API patterns.
+ * When strict mode is enabled with `failOnViolation`, throws an error.
+ * Otherwise, emits warnings.
+ *
+ * @param content - The script content to validate
+ * @param filePath - The file path for error reporting
+ * @param strict - Strict mode configuration
+ */
+export declare function validateClientScript(content: string, filePath: string, strict?: boolean | StrictModeConfig, 
+/**
+ * The view this script was authored in, when `filePath` is a layout that view
+ * was composed into. Reported alongside, because naming only the layout sends
+ * the reader to a file that does not contain the offending code (#1836).
+ */
+originFilePath?: string): void;

package/dist/script-validation.js

@@ -0,0 +1,179 @@
+import { contentKey, renderMemo } from "./render-memo.js";
+import { stripCommentsAndLiterals } from "./strip-literals.js";
+const verdicts = renderMemo(256);
+export const PROHIBITED_DOM_PATTERNS = [
+  {
+    pattern: /document\.getElementById\s*\(/g,
+    message: "document.getElementById() is prohibited",
+    suggestion: 'Use useRef("name") instead'
+  },
+  {
+    pattern: /document\.querySelector\s*\(/g,
+    message: "document.querySelector() is prohibited",
+    suggestion: 'Use useRef("name") instead'
+  },
+  {
+    pattern: /document\.querySelectorAll\s*\(/g,
+    message: "document.querySelectorAll() is prohibited",
+    suggestion: 'Use useRef("name") and access children instead'
+  },
+  {
+    pattern: /document\.getElementsBy\w+\s*\(/g,
+    message: "document.getElementsBy*() is prohibited",
+    suggestion: 'Use useRef("name") instead'
+  },
+  {
+    pattern: /document\.createElement\s*\(/g,
+    message: "document.createElement() is prohibited",
+    suggestion: "Use template directives or component composition instead"
+  },
+  {
+    pattern: /document\.activeElement(?![A-Za-z])/g,
+    message: "document.activeElement is prohibited",
+    suggestion: "Use useRef() to track focused elements"
+  },
+  {
+    pattern: /document\.title\s*=/g,
+    message: "document.title assignment is prohibited",
+    suggestion: "Use useTitle() from composables"
+  },
+  {
+    pattern: /document\.cookie(?![A-Za-z])/g,
+    message: "document.cookie is prohibited",
+    suggestion: "Use useCookie() from composables"
+  },
+  {
+    pattern: /document\.addEventListener\s*\(/g,
+    message: "document.addEventListener() is prohibited",
+    suggestion: "Use useEventListener() or template @event directives"
+  },
+  {
+    pattern: /window\.location(?![A-Za-z])/g,
+    message: "window.location is prohibited",
+    suggestion: "Use navigate() or useRoute()"
+  },
+  {
+    pattern: /window\.history(?![A-Za-z])/g,
+    message: "window.history is prohibited",
+    suggestion: "Use navigate(), goBack(), goForward()"
+  },
+  {
+    pattern: /window\.addEventListener\s*\(/g,
+    message: "window.addEventListener() is prohibited",
+    suggestion: "Use useEventListener() or @click directives"
+  },
+  {
+    pattern: /(?:\bwindow\.)?localStorage(?![A-Za-z])/g,
+    message: "window.localStorage is prohibited",
+    suggestion: "Use useLocalStorage() from composables \u2014 or @appearanceBootstrap if this must run before first paint, where the runtime does not exist yet"
+  },
+  {
+    pattern: /window\.sessionStorage(?![A-Za-z])/g,
+    message: "window.sessionStorage is prohibited",
+    suggestion: "Use useSessionStorage() from composables"
+  },
+  {
+    pattern: /window\.scrollTo\s*\(/g,
+    message: "window.scrollTo() is prohibited",
+    suggestion: "Use useScroll().scrollTo() from composables"
+  },
+  {
+    pattern: /window\.alert\s*\(/g,
+    message: "window.alert() is prohibited",
+    suggestion: "Use stx modal/dialog APIs instead"
+  },
+  {
+    pattern: /window\.confirm\s*\(/g,
+    message: "window.confirm() is prohibited",
+    suggestion: "Use stx modal/dialog APIs instead"
+  },
+  {
+    pattern: /window\.prompt\s*\(/g,
+    message: "window.prompt() is prohibited",
+    suggestion: "Use stx modal/dialog APIs instead"
+  },
+  {
+    pattern: /(?<!\w)setTimeout\s*\(/g,
+    message: "setTimeout() is prohibited",
+    suggestion: "Use useTimeout() or useDebounce() from composables"
+  },
+  {
+    pattern: /(?<!\w)setInterval\s*\(/g,
+    message: "setInterval() is prohibited",
+    suggestion: "Use useInterval() from composables"
+  },
+  {
+    pattern: /(?<!\w)clearTimeout\s*\(/g,
+    message: "clearTimeout() is prohibited",
+    suggestion: "Use useTimeout().stop() or useDebounce().cancel()"
+  },
+  {
+    pattern: /(?<!\w)clearInterval\s*\(/g,
+    message: "clearInterval() is prohibited",
+    suggestion: "Use useInterval().pause()"
+  },
+  {
+    pattern: /(?<!\w)location\.href\s*=/g,
+    message: "location.href assignment is prohibited",
+    suggestion: "Use navigate() instead"
+  },
+  {
+    pattern: /(?<!\w)location\.assign\s*\(/g,
+    message: "location.assign() is prohibited",
+    suggestion: "Use navigate() instead"
+  },
+  {
+    pattern: /(?<!\w)location\.replace\s*\(/g,
+    message: "location.replace() is prohibited",
+    suggestion: "Use navigate() instead"
+  }
+];
+export function validateClientScript(content, filePath, strict, originFilePath) {
+  const strictConfig = typeof strict === "boolean" ? { enabled: strict, failOnViolation: strict } : strict ?? { enabled: !1 };
+  if (!strictConfig.enabled)
+    return;
+  const memoKey = contentKey(content, filePath, originFilePath, JSON.stringify(strictConfig)), remembered = verdicts.get(memoKey);
+  if (remembered !== void 0) {
+    if (remembered && strictConfig.failOnViolation)
+      throw Error(remembered);
+    return;
+  }
+  const allowPatterns = strictConfig.allowPatterns ?? [], errors = [], scannable = stripCommentsAndLiterals(content.replace(/\{\{--[\s\S]*?--\}\}/g, (match) => match.replace(/[^\n]/g, " ")));
+  for (const { pattern, message, suggestion } of PROHIBITED_DOM_PATTERNS) {
+    if (allowPatterns.some((allowed) => /\w/.test(allowed) && message.includes(allowed)))
+      continue;
+    pattern.lastIndex = 0;
+    const matches = scannable.match(pattern);
+    if (matches && matches.length > 0) {
+      const lines = scannable.split(`
+`), sourceLines = content.split(`
+`), lineNumbers = [];
+      lines.forEach((line, index) => {
+        pattern.lastIndex = 0;
+        if (pattern.test(line))
+          lineNumbers.push(index + 1);
+      });
+      const locationInfo = lineNumbers.length > 0 ? ` (script line${lineNumbers.length > 1 ? "s" : ""} ${lineNumbers.join(", ")})` : "", quoted = lineNumbers.slice(0, 3).map((n) => `        ${n} | ${(sourceLines[n - 1] ?? "").trim().slice(0, 100)}`).join(`
+`), snippet = quoted ? `
+${quoted}` : "";
+      errors.push(`  \u2717 ${message}${locationInfo}
+    \u2192 ${suggestion}${snippet}`);
+    }
+  }
+  if (errors.length === 0) {
+    verdicts.set(memoKey, "");
+    return;
+  }
+  const rel = (p) => {
+    const cwd = `${process.cwd()}/`;
+    return p.startsWith(cwd) ? p.slice(cwd.length) : p;
+  }, baseMessage = `[STX] DOM API violation in ${originFilePath && originFilePath !== filePath ? `${rel(originFilePath)} (composed into ${rel(filePath)})` : rel(filePath)}:
+${errors.join(`
+`)}
+  Tip: prefer useRef(), navigate(), and composables for component code`;
+  verdicts.set(memoKey, baseMessage);
+  if (strictConfig.failOnViolation)
+    throw Error(baseMessage);
+  else
+    console.warn(baseMessage);
+}