@stacksjs/stx 0.2.175 → 0.2.177

package/dist/ssr.js

@@ -4,6 +4,7 @@ import { errorLogger } from "./error-handling.js";
 import { processDirectives } from "./process.js";
 import { extractVariables } from "./utils.js";
 import { patternToRegex } from "stx-router";
+import { serializeSetCookie } from "./cookie-serialize.js";
 
 export class MemorySessionStore {
   store = new Map;
@@ -89,22 +90,7 @@ function parseCookies(cookieHeader) {
   }, {});
 }
 function serializeCookie(name, value, options = {}) {
-  let cookie = `${encodeURIComponent(name)}=${encodeURIComponent(value)}`;
-  if (options.maxAge !== void 0)
-    cookie += `; Max-Age=${options.maxAge}`;
-  if (options.expires)
-    cookie += `; Expires=${options.expires.toUTCString()}`;
-  if (options.path)
-    cookie += `; Path=${options.path}`;
-  if (options.domain)
-    cookie += `; Domain=${options.domain}`;
-  if (options.secure)
-    cookie += "; Secure";
-  if (options.httpOnly)
-    cookie += "; HttpOnly";
-  if (options.sameSite)
-    cookie += `; SameSite=${options.sameSite}`;
-  return cookie;
+  return serializeSetCookie(name, value, options);
 }
 function generateCsrfToken() {
   return crypto.randomBytes(32).toString("hex");

package/dist/stx-virtual-ts.d.ts

@@ -2,9 +2,9 @@
  * Pull the script blocks out of a `.stx` source, with the line each body starts on.
  *
  * `<script server>` and `<script client>` are recognised by attribute. A bare
- * `<script>` is reported as `plain`: it ships to the browser verbatim without
- * the auto-import preamble, so it is a different checking context and callers
- * may want to skip it.
+ * `<script>` is reported as `plain` so a caller can tell which tag the author
+ * actually wrote — NOT so it can be skipped. It is a client block; `client` is
+ * an explicit alias for the default, not a separate kind (stacksjs/stx#1920).
  */
 export declare function extractScriptBlocks(source: string): ScriptBlock[];
 /**
@@ -45,6 +45,30 @@ export declare function substituteInterpolations(value: string): string;
  * fit and would shift the line.
  */
 export declare function substituteInterpolationsInPlace(code: string): string;
+/**
+ * Blank stx directives that a script body writes to generate JavaScript.
+ *
+ * A template can loop inside a script — building a lookup table from server
+ * data is the obvious use — and the directive is expanded away long before the
+ * browser sees it:
+ *
+ *   const data = {
+ *     &#64;foreach(features as f)
+ *       '{{ f.id }}': { title: '{{ f.title }}' },
+ *     &#64;endforeach
+ *   }
+ *
+ * To TypeScript the directive line is a syntax error, and one of those mutes
+ * semantic checking for the WHOLE program, not just the file. So checking bare
+ * `<script>` blocks (#1920) made a valid page report 37 invented syntax errors
+ * — and a checker that invents errors gets muted, which is the failure mode
+ * this file exists to avoid.
+ *
+ * Blanked rather than removed so every line number after it still points at the
+ * line the author wrote. Only a directive ALONE on its line is matched: that is
+ * how they are written, and it cannot swallow code sharing the line.
+ */
+export declare function blankScriptDirectives(code: string): string;
 /**
  * Every checkable expression in the markup, with the position it occupies.
  *
@@ -107,7 +131,23 @@ export declare function splitTopLevelImports(code: string): { imports: string, b
  * So the incentive runs the right way: declare a payload and the names are
  * checked against the server block, or do not and they are `any`.
  */
-export declare function clientPayloadDeclarations(serverCode: string): string;
+/**
+ * Top-level `interface X {…}` / `type X = …` statements, with their source text.
+ *
+ * The payload projection wraps the whole server body in a scope function so the
+ * checker can infer each published value's type from real code. That works for
+ * VALUES and traps TYPES: an `interface AutofixState` declared in
+ * `<script server>` lives inside that function, so a `<script client>` block in
+ * the same file naming it got `Cannot find name 'AutofixState'` — an error about
+ * code that is correct and runs (stacksjs/stx#1924).
+ *
+ * Scanned at depth zero so an interface declared inside a helper is not lifted
+ * out of the scope it belongs to. The brace matcher walks the real source rather
+ * than a blanked copy, because the declaration's BODY is what has to be carried
+ * across, not just its name.
+ */
+export declare function extractTypeDeclarations(code: string): Array<{ name: string, text: string }>;
+export declare function clientPayloadDeclarations(serverCode: string, clientCode?: string): string;
 /**
  * Declarations at the TOP LEVEL of a block, ignoring anything nested.
  *
@@ -157,6 +197,33 @@ export declare function crossScopeCollisions(blocks: readonly ScriptBlock[]): st
  * `const`, and that form is documented stx syntax, not a mistake.
  */
 export declare function expressionStatement(expression: TemplateExpression): { text: string, prefixLength: number } | null;
+/**
+ * Rewrite relative module specifiers to absolute paths against the real file.
+ *
+ * A block's virtual buffer is written into the state directory, and TypeScript
+ * resolves a relative specifier against the file that CONTAINS it — so
+ * `../target`, written in `pages/deep/rel.stx`, was looked for next to
+ * `.stx/typecheck/` and reported as a missing module (stacksjs/stx#1928).
+ *
+ * A `paths` alias to the same file resolved fine, because those go through the
+ * absolute `baseUrl` the checker emits. That asymmetry is the whole bug: a
+ * relative import is the first thing anyone writes and what every editor's
+ * auto-import produces, so an app hitting it either rewrites correct imports
+ * into aliases to appease the checker, or mutes the checker.
+ *
+ * Rewriting each specifier is preferred over pointing the program at the source
+ * directory — `rootDirs`, the built-in answer for a virtual layout, MERGES its
+ * entries into one namespace, so `./util` from one checked page could silently
+ * resolve to a different page's `util` when both directories are roots. Each
+ * buffer knows exactly one origin, so resolving per file cannot cross-talk.
+ *
+ * Textual rather than parsed, and deliberately: `Bun.Transpiler.scanImports`
+ * erases `import type`, which is the form a type-checker cares about most. The
+ * cost is that the literal text `from './x'` inside a string or comment is
+ * rewritten too — inert, since this buffer is never executed, and it cannot
+ * change a line count, so every diagnostic still lands on the author's line.
+ */
+export declare function absolutizeRelativeSpecifiers(code: string, originDir: string): string;
 /**
  * Build one line-aligned TypeScript buffer for a whole `.stx` file.
  *
@@ -255,6 +322,7 @@ export declare interface TemplateBinding {
 }
 export declare interface BuildVirtualOptions {
   templateExpressions?: boolean
+  originDir?: string
   globals?: boolean
   runtimeGlobals?: boolean
 }

package/dist/stx-virtual-ts.js

@@ -1,3 +1,4 @@
+import path from "node:path";
 import { stripCommentsAndLiterals } from "./strip-literals.js";
 import { STX_RUNTIME_GLOBALS } from "./runtime-globals.js";
 const SCRIPT_RE = /<script(\s[^>]*)?>([\s\S]*?)<\/script>/gi;
@@ -105,6 +106,42 @@ export function substituteInterpolationsInPlace(code) {
 `.repeat(newlines)}`;
   });
 }
+const SCRIPT_BODY_DIRECTIVES = [
+  "foreach",
+  "endforeach",
+  "forelse",
+  "endforelse",
+  "for",
+  "endfor",
+  "while",
+  "endwhile",
+  "empty",
+  "if",
+  "elseif",
+  "else",
+  "endif",
+  "unless",
+  "endunless",
+  "isset",
+  "endisset",
+  "switch",
+  "case",
+  "default",
+  "endswitch",
+  "auth",
+  "endauth",
+  "guest",
+  "endguest",
+  "env",
+  "endenv",
+  "once",
+  "endonce",
+  "break",
+  "continue"
+], SCRIPT_BODY_DIRECTIVE_RE = new RegExp(String.raw`^[ \t]*@(?:${SCRIPT_BODY_DIRECTIVES.join("|")})\b[ \t]*(\([^\n)]*\))?[ \t]*$`, "gm");
+export function blankScriptDirectives(code) {
+  return code.replace(SCRIPT_BODY_DIRECTIVE_RE, (match) => match.replace(/[^\n]/g, " "));
+}
 const NON_EXPRESSION_ATTRS = new Set([
   "x-cloak",
   "x-ref",
@@ -294,27 +331,87 @@ export function splitTopLevelImports(code) {
   return { imports: imports.join(`
 `), body };
 }
-export function clientPayloadDeclarations(serverCode) {
-  const published = extractClientPayloadNames(serverCode);
+export function extractTypeDeclarations(code) {
+  const searchable = stripCommentsAndLiterals(code), depthAt = Array(searchable.length);
+  let depth = 0;
+  for (let i = 0;i < searchable.length; i++) {
+    const c = searchable[i];
+    if (c === "}" || c === ")" || c === "]")
+      depth = Math.max(0, depth - 1);
+    depthAt[i] = depth;
+    if (c === "{" || c === "(" || c === "[")
+      depth++;
+  }
+  const found = [], start = /^[ \t]*(?:export[ \t]+)?(interface|type)[ \t]+([A-Za-z_$][\w$]*)/gm;
+  let match;
+  while ((match = start.exec(searchable)) !== null) {
+    if (depthAt[match.index] !== 0)
+      continue;
+    const kind = match[1], name = match[2];
+    let end;
+    if (kind === "interface") {
+      const open = searchable.indexOf("{", match.index);
+      if (open === -1)
+        continue;
+      let depth = 0;
+      end = -1;
+      for (let i = open;i < searchable.length; i++)
+        if (searchable[i] === "{")
+          depth++;
+        else if (searchable[i] === "}" && --depth === 0) {
+          end = i + 1;
+          break;
+        }
+      if (end === -1)
+        continue;
+    } else {
+      let depth = 0;
+      end = searchable.length;
+      for (let i = searchable.indexOf("=", match.index) + 1;i < searchable.length; i++) {
+        const c = searchable[i];
+        if (c === "{" || c === "[" || c === "(" || c === "<")
+          depth++;
+        else if (c === "}" || c === "]" || c === ")" || c === ">")
+          depth--;
+        else if (depth <= 0 && (c === ";" || c === `
+` && !/[=|&,<([{]\s*$/.test(searchable.slice(Math.max(0, i - 40), i)))) {
+          end = c === ";" ? i + 1 : i;
+          break;
+        }
+      }
+    }
+    found.push({ name, text: code.slice(match.index, end).replace(/^[ \t]*export[ \t]+/, "") });
+    start.lastIndex = end;
+  }
+  return found;
+}
+function declaredTypeNames(code) {
+  return new Set(extractTypeDeclarations(code).map((entry) => entry.name));
+}
+export function clientPayloadDeclarations(serverCode, clientCode = "") {
+  const published = extractClientPayloadNames(serverCode), ownTypes = declaredTypeNames(clientCode), serverTypes = extractTypeDeclarations(serverCode).filter((entry) => !ownTypes.has(entry.name)).map((entry) => entry.text);
   if (!published) {
     const scraped = collectBlockDeclarations(serverCode);
-    if (scraped.length === 0)
+    if (scraped.length === 0 && serverTypes.length === 0)
       return "";
     return [
       "",
       `// ${SCRAPED_COMMENT}`,
+      ...serverTypes,
       ...scraped.map((name) => `declare var ${name}: any`)
     ].join(`
 `);
   }
   if (published.length === 0)
-    return "";
+    return serverTypes.length > 0 ? ["", `// ${PAYLOAD_COMMENT}`, ...serverTypes].join(`
+`) : "";
   const { imports, body } = splitTopLevelImports(serverCode), scopeBody = body.replace(/^[ \t]*export[ \t]+(?=(?:const|let|var|function|async|class)\b)/gm, ""), parts = [
     "",
     `// ${PAYLOAD_COMMENT}`
   ];
   if (imports)
     parts.push(imports);
+  parts.push(...serverTypes);
   parts.push(`async function ${PAYLOAD_SCOPE}() {`, scopeBody, `  return { ${published.join(", ")} }`, "}", `type ${PAYLOAD_TYPE} = Awaited<ReturnType<typeof ${PAYLOAD_SCOPE}>>`, ...published.map((name) => `declare var ${name}: ${PAYLOAD_TYPE}[${JSON.stringify(name)}]`));
   return parts.join(`
 `);
@@ -390,11 +487,20 @@ export function expressionStatement(expression) {
   const prefix = ";void ((";
   return { text: `${prefix}${code}));`, prefixLength: prefix.length };
 }
+const RELATIVE_SPECIFIER_RE = /(\bfrom\s*|\bimport\s*\(\s*|\bimport\s+)(['"])(\.{1,2}\/[^'"\n]*)\2/g;
+export function absolutizeRelativeSpecifiers(code, originDir) {
+  if (!originDir)
+    return code;
+  return code.replace(RELATIVE_SPECIFIER_RE, (_whole, prefix, quote, specifier) => {
+    const absolute = path.resolve(originDir, specifier).replace(/\\/g, "/");
+    return `${prefix}${quote}${absolute}${quote}`;
+  });
+}
 export function buildVirtualTypeScript(source, options = {}) {
   const blocks = extractScriptBlocks(source), sourceLines = source.split(`
 `), lines = Array.from({ length: sourceLines.length }, () => ""), lineMap = new Map;
   for (const block of blocks)
-    block.code.split(`
+    absolutizeRelativeSpecifiers(block.code, options.originDir ?? "").split(`
 `).forEach((text, i) => {
       const index = block.startLine - 1 + i;
       if (index < lines.length)

package/dist/stx.d.ts

@@ -199,11 +199,42 @@ declare function useSearchParams(): {
 // Data fetching
 // ============================================================================
 
-interface StxQueryResult<T> {
+/** How one run of a request should behave. */
+interface StxRefetchOptions {
+  /**
+   * Refresh without touching `loading` or clearing the current error.
+   *
+   * A poll refreshes data that is already on screen, so driving the first-load
+   * state from it puts a spinner over a populated view on every tick — the
+   * reason a polling view could not use these primitives at all (#1929). Bind
+   * `isFetching` for a subtle in-flight indicator instead.
+   */
+  background?: boolean
+}
+
+interface StxFetchResult<T> {
   data: StxSignal<T | null>
+  /** True while a first-load request is in flight. A background one leaves it alone. */
   loading: StxSignal<boolean>
+  /** True while ANY request is in flight, background ones included. */
+  isFetching: StxSignal<boolean>
   error: StxSignal<Error | null>
-  refetch: () => Promise<void>
+  refetch: (_options?: StxRefetchOptions) => Promise<void>
+}
+
+/*
+ * `useQuery` returns more than `useFetch` does, and declaring one shape for
+ * both hid it: `isStale` and `invalidate` existed at runtime and were invisible
+ * to the type, so reading either was an error on a value that was really there
+ * (#1929). Extending rather than widening the shared interface, because the
+ * inverse mistake is worse — declaring `invalidate` on `useFetch` would
+ * type-check a call to something that is undefined at runtime.
+ */
+interface StxQueryResult<T> extends StxFetchResult<T> {
+  /** True when cached data is on screen while a revalidation runs. */
+  isStale: StxSignal<boolean>
+  /** Drop this key from the cache and refetch. */
+  invalidate: (_options?: StxRefetchOptions) => Promise<void>
 }
 
 interface StxMutationResult<T> {
@@ -213,7 +244,7 @@ interface StxMutationResult<T> {
   mutate: (body?: unknown) => Promise<T>
 }
 
-declare function useFetch<T = any>(_url: string, _options?: any): StxQueryResult<T>
+declare function useFetch<T = any>(_url: string, _options?: any): StxFetchResult<T>
 declare function useQuery<T = any>(_url: string, _options?: any): StxQueryResult<T>
 declare function useMutation<T = any>(_url: string, _options?: any): StxMutationResult<T>
 
@@ -271,17 +302,45 @@ declare function useOptimistic<T = any, A = any>(
 // DOM utilities
 // ============================================================================
 
+/**
+ * Options the runtime reads, including the target it binds to.
+ *
+ * The target travels HERE rather than in a leading parameter, because that is
+ * what the implementation does: `var target = (options && options.target) || window`.
+ */
+interface StxEventListenerOptions {
+  /** Element, selector, or document/window. Defaults to `window`. */
+  target?: Window | Document | HTMLElement | string | null
+  capture?: boolean
+  passive?: boolean
+  once?: boolean
+}
+
+/*
+ * Event first, then handler, then options (stacksjs/stx#1923).
+ *
+ * This was declared target-first while the runtime has always been
+ * event-first, so the two disagreed in the worst possible direction: `_target`
+ * accepted `string`, so the CORRECT call got as far as reading 'keydown' as a
+ * selector before failing on the handler, and an author who trusted the type
+ * and added a target wrote `useEventListener(window, 'keydown', fn)` — which
+ * binds an event named "window" with the string 'keydown' as its handler, and
+ * silently attaches nothing.
+ *
+ * `browser-composables.ts` had it right all along; the package shipped two
+ * declarations of one name with different arities and the registry got the
+ * wrong one. Same shape as the `reactive` split: one name, two conventions, and
+ * no way for the call site to tell which it has.
+ */
 declare function useEventListener<K extends keyof WindowEventMap>(
-  _target: Window | Document | HTMLElement | string | null,
   _event: K,
   _handler: (event: WindowEventMap[K]) => void,
-  _options?: boolean | AddEventListenerOptions,
+  _options?: StxEventListenerOptions,
 ): StxCleanup
 declare function useEventListener(
-  _target: Window | Document | HTMLElement | string | null,
   _event: string,
   _handler: (event: Event) => void,
-  _options?: boolean | AddEventListenerOptions,
+  _options?: StxEventListenerOptions,
 ): StxCleanup
 declare function useScrollLock(
   _target?: HTMLElement | null | { current?: HTMLElement | null, value?: HTMLElement | null } | (() => HTMLElement | null | undefined),

package/dist/template-hydrator.d.ts

@@ -20,7 +20,7 @@ export declare function hydrateTemplate(compiled: CompiledTemplate, requestConte
  * templates aren't serialized into the compiled template, so use the function
  * form in production.)
  */
-export declare function hydrateTemplateStream(compiled: CompiledTemplate, requestContext?: Record<string, any>): Promise<{ html: string, boundaries?: { id: string, render: () => Promise<string> }[], redirect?: string }>;
+export declare function hydrateTemplateStream(compiled: CompiledTemplate, requestContext?: Record<string, any>): Promise<{ html: string, boundaries?: { id: string, render: () => Promise<string> }[], redirect?: string, cookies?: string[] }>;
 /**
  * Hydrate a fragment (for SPA navigation).
  * Same as hydrateTemplate but returns the fragment portion.

package/dist/template-hydrator.js

@@ -6,9 +6,9 @@ export async function hydrateTemplate(compiled, requestContext = {}) {
   return (await runHydration(compiled, requestContext)).html;
 }
 export async function hydrateTemplateStream(compiled, requestContext = {}) {
-  const { html, context, redirect } = await runHydration(compiled, requestContext);
+  const { html, context, redirect, cookies } = await runHydration(compiled, requestContext);
   if (redirect)
-    return { html, redirect };
+    return { html, redirect, cookies };
   const { extractStreamBoundaries } = await import("./streaming.js");
   let boundaries = extractStreamBoundaries(context);
   const templates = compiled.streamTemplates;
@@ -22,7 +22,7 @@ export async function hydrateTemplateStream(compiled, requestContext = {}) {
     })), tplIds = new Set(tplBoundaries.map((b) => b.id));
     boundaries = [...(boundaries || []).filter((b) => !tplIds.has(b.id)), ...tplBoundaries];
   }
-  return { html, boundaries: boundaries && boundaries.length > 0 ? boundaries : void 0 };
+  return { html, boundaries: boundaries && boundaries.length > 0 ? boundaries : void 0, cookies };
 }
 async function runHydration(compiled, requestContext) {
   const context = {
@@ -45,9 +45,9 @@ async function runHydration(compiled, requestContext) {
     cookies: requestContext.cookies ?? {}
   });
   if (action.redirect)
-    return { html: compiled.html, context, redirect: action.redirect };
+    return { html: compiled.html, context, redirect: action.redirect, cookies: action.cookies };
   if (!hasPlaceholders(compiled.html))
-    return { html: compiled.html, context };
+    return { html: compiled.html, context, cookies: action.cookies };
   const values = new Map;
   for (const [token, info] of Object.entries(compiled.placeholders))
     if (info.expression)
@@ -60,7 +60,7 @@ async function runHydration(compiled, requestContext) {
       } catch {
         values.set(token, "");
       }
-  return { html: replacePlaceholders(compiled.html, values), context };
+  return { html: replacePlaceholders(compiled.html, values), context, cookies: action.cookies };
 }
 export async function hydrateFragment(compiled, requestContext = {}) {
   if (!compiled.hasServerScripts && !hasPlaceholders(compiled.fragment))

package/dist/theme-tokens.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Role-named colours, so a component can say what a colour is FOR.
+ *
+ * `@stacksjs/components` named palette shades directly — `bg-gray-100`,
+ * `text-gray-600`, `ring-indigo-600` — with a `dark:` variant beside each. That
+ * renders correctly and is impossible for a host app to redirect by meaning: you
+ * can remap `gray`, but you cannot say "every border in the library comes from
+ * `--stx-line`", because nothing distinguishes a gray that is a border from a
+ * gray that is muted text (stacksjs/stx#1930).
+ *
+ * These tokens are added to the BASE theme rather than shipped as an opt-in
+ * preset. That matters for one reason: a component that says `text-fg-muted`
+ * must resolve in every app, or adopting the component library would silently
+ * require a config change and render unstyled without it. Adding names is purely
+ * additive — no existing utility changes, and no opacity modifier on an existing
+ * palette colour turns into `color-mix()`.
+ *
+ * ## Where the values come from
+ *
+ * Each token names a shade in crosswind's own palette rather than carrying a hex
+ * value, and the light/dark pairs are the ones the component library already
+ * used most — measured, not invented:
+ *
+ *     text-gray-900 dark:text-gray-100   ×70   ->  text-fg
+ *     text-gray-500 dark:text-gray-400   ×24   ->  text-fg-soft
+ *     border-gray-200 dark:border-gray-700 ×21 ->  border-line
+ *
+ * So migrating a component to a token is appearance-preserving wherever its
+ * pairing was the dominant one, and the defaults stay in step with the palette
+ * because they are resolved from it rather than copied.
+ *
+ * ## How dark mode works
+ *
+ * Each token resolves to `var(--stx-<name>, <light value>)`, and
+ * {@link semanticTokenCSS} emits `:root` and `.dark` blocks that set the
+ * variable. So `text-fg-muted` is one class that is correct in both modes, and
+ * an app overrides a role by setting the variable — at runtime, with no rebuild.
+ *
+ * The fallback is deliberately the LIGHT value. If the variable block ever fails
+ * to reach a page, light mode is still correct and dark mode falls back to the
+ * light colour: degraded, but readable. The alternative — no fallback — would
+ * render the token as an invalid colour and take the whole component's styling
+ * with it.
+ *
+ * @module theme-tokens
+ */
+/** A role, and the palette shades that back it in each mode. */
+export interface SemanticToken {
+    /** Shade reference, e.g. `gray-900`. Resolved against the live palette. */
+    light: string;
+    dark: string;
+    /** What the role means, for the generated docs and for anyone reading here. */
+    description: string;
+}
+/**
+ * The role vocabulary.
+ *
+ * Five text roles rather than the usual three because the library genuinely
+ * distinguishes five: 900, 700, 600, 500 and 400 all appear as body-ish text
+ * with different dark partners. Collapsing them here would have been a redesign
+ * rather than a migration.
+ */
+export declare const SEMANTIC_TOKENS: Record<string, SemanticToken>;
+/** The CSS custom property that backs a role. */
+export declare function tokenVariable(name: string): string;
+type Palette = Record<string, unknown>;
+/**
+ * The palette entries to merge into `theme.colors`.
+ *
+ * Every entry is `var(--stx-<name>, <light value>)`, so the name works as an
+ * ordinary utility (`bg-surface`, `text-fg-muted`, `ring-line-strong`) and an
+ * app can move it by setting the variable.
+ */
+export declare function semanticColors(palette: Palette): Record<string, string>;
+/**
+ * The `:root` / `.dark` block that gives each role its value per mode.
+ *
+ * Emitted ahead of the generated utilities so an app's own stylesheet — which
+ * comes after — can override any of it without a specificity fight.
+ *
+ * `.dark` matches the class strategy the rest of stx uses (`dark:` variants
+ * compile to `.dark .dark\:x`), so a token and a `dark:` utility on the same
+ * page agree about what dark mode is.
+ */
+export declare function semanticTokenCSS(palette: Palette): string;
+/** Every variable a role token reads, for documentation and tooling. */
+export declare function semanticTokenNames(): string[];
+export {};

package/dist/theme-tokens.js

@@ -0,0 +1,71 @@
+export const SEMANTIC_TOKENS = {
+  fg: { light: "gray-900", dark: "gray-100", description: "Primary text" },
+  "fg-strong": { light: "gray-700", dark: "gray-300", description: "Labels, secondary headings" },
+  "fg-muted": { light: "gray-600", dark: "gray-400", description: "Supporting text" },
+  "fg-soft": { light: "gray-500", dark: "gray-400", description: "De-emphasised text" },
+  "fg-subtle": { light: "gray-400", dark: "gray-500", description: "Placeholders, disabled text" },
+  surface: { light: "gray-50", dark: "gray-800", description: "Page and panel background" },
+  "surface-raised": { light: "gray-100", dark: "gray-700", description: "Cards, popovers" },
+  "surface-sunken": { light: "gray-200", dark: "gray-700", description: "Wells, track backgrounds" },
+  line: { light: "gray-200", dark: "gray-700", description: "Default border, divider" },
+  "line-strong": { light: "gray-300", dark: "gray-600", description: "Input border, focus ring track" },
+  accent: { light: "indigo-600", dark: "indigo-400", description: "Primary action, selected state" },
+  info: { light: "blue-600", dark: "blue-400", description: "Informational emphasis, links" },
+  danger: { light: "red-600", dark: "red-400", description: "Errors, destructive actions" },
+  success: { light: "green-600", dark: "green-400", description: "Confirmation" },
+  warning: { light: "yellow-500", dark: "yellow-400", description: "Caution" },
+  "accent-solid": { light: "indigo-600", dark: "indigo-500", description: "Primary button fill" },
+  "info-solid": { light: "blue-600", dark: "blue-500", description: "Informational fill" },
+  "danger-solid": { light: "red-600", dark: "red-500", description: "Destructive button fill" },
+  "success-solid": { light: "green-600", dark: "green-500", description: "Confirmation fill" }
+};
+export function tokenVariable(name) {
+  return `--stx-${name}`;
+}
+function resolveShade(palette, reference) {
+  const split = reference.lastIndexOf("-");
+  if (split === -1)
+    return typeof palette[reference] === "string" ? palette[reference] : void 0;
+  const family = palette[reference.slice(0, split)];
+  if (!family || typeof family !== "object")
+    return;
+  const value = family[reference.slice(split + 1)];
+  return typeof value === "string" ? value : void 0;
+}
+export function semanticColors(palette) {
+  const colors = {};
+  for (const [name, token] of Object.entries(SEMANTIC_TOKENS)) {
+    const light = resolveShade(palette, token.light);
+    if (light === void 0)
+      continue;
+    colors[name] = `var(${tokenVariable(name)}, ${light})`;
+  }
+  return colors;
+}
+export function semanticTokenCSS(palette) {
+  const light = [], dark = [];
+  for (const [name, token] of Object.entries(SEMANTIC_TOKENS)) {
+    const lightValue = resolveShade(palette, token.light), darkValue = resolveShade(palette, token.dark);
+    if (lightValue === void 0)
+      continue;
+    light.push(`  ${tokenVariable(name)}: ${lightValue};`);
+    if (darkValue !== void 0)
+      dark.push(`  ${tokenVariable(name)}: ${darkValue};`);
+  }
+  if (light.length === 0)
+    return "";
+  return [
+    "/* stx role tokens \u2014 override any of these to re-theme by meaning. */",
+    ":root {",
+    ...light,
+    "}",
+    ".dark {",
+    ...dark,
+    "}",
+    ""
+  ].join(`
+`);
+}
+export function semanticTokenNames() {
+  return Object.keys(SEMANTIC_TOKENS).map(tokenVariable);
+}

package/dist/typecheck.d.ts

@@ -14,8 +14,13 @@ export type { ScriptBlock, ScriptKind } from './stx-virtual-ts';
  * in a `<script server>` block both reported "Cannot redeclare block-scoped
  * variable", and those are ordinary names for server-rendered page data. It is
  * appended rather than prepended so the line numbers above it are untouched.
+ *
+ * `originDir` is the directory the `.stx` file really lives in. The buffer is
+ * written into the state directory, and tsc resolves a relative specifier
+ * against the file containing it — so without this, `../target` was looked for
+ * next to `.stx/typecheck/` (#1928).
  */
-export declare function buildVirtualSource(block: ScriptBlock, serverCode?: string): string;
+export declare function buildVirtualSource(block: ScriptBlock, serverCode?: string, originDir?: string): string;
 /** Virtual path for a block, stable and traceable back to its origin. */
 export declare function virtualPathFor(filePath: string, kind: DiagnosticOrigin, index: number): string;
 /** Map a virtual path back to the `.stx` file it came from. */