@colixsystems/widget-sdk 0.198.0 → 0.200.0

package/dist/cli.js

@@ -5,7 +5,7 @@
 //                                                          — REQ-WSDK-DEVKIT local dev server
 
 import { readFileSync } from "node:fs";
-import { basename, resolve } from "node:path";
+import { basename, dirname, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { argv, exit, stderr, stdout } from "node:process";
 import {
@@ -15,6 +15,10 @@ import {
   narrowManifestForFile,
 } from "./linter.js";
 import { startDevServer } from "./devserver.js";
+import {
+  bundledAssetDirectoryOf,
+  loadBundledAssets,
+} from "./bundled-assets-fs.js";
 
 function usage() {
   stderr.write(
@@ -22,6 +26,8 @@ function usage() {
       "  appstudio-widget lint <file.jsx...> [--manifest <path>]\n" +
       "    Pass every file the widget ships plus --manifest to also check " +
       "that each styleSchema field is actually read.\n" +
+      "    An assets/ directory beside a file is checked too: every image " +
+      "and sound in it must be a type the package may bundle.\n" +
       "  appstudio-widget dev <entry.jsx|widget-dir> [--port <n>] [--manifest <path>]\n" +
       "    A directory containing widget.json runs in multi-file mode " +
       "(REQ-WSDK-DEVKIT v2): the dev server reads the canonical web entry, " +
@@ -57,6 +63,28 @@ function parseFlags(args) {
   return { flags, positionals };
 }
 
+// One read per assets/ directory, however many linted files sit beside it.
+function loadAssetsBesideFiles(filePaths) {
+  const byDirectory = new Map();
+  for (const filePath of filePaths) {
+    const assetsDir = bundledAssetDirectoryOf(dirname(filePath));
+    if (!byDirectory.has(assetsDir)) {
+      byDirectory.set(assetsDir, loadBundledAssets(assetsDir));
+    }
+  }
+  return byDirectory;
+}
+
+function assetFindings(assets) {
+  return assets.errors.map((error) => ({
+    rule: error.code,
+    severity: "error",
+    label: error.message,
+    line: 0,
+    snippet: "",
+  }));
+}
+
 async function loadManifest(path) {
   const abs = resolve(path);
   if (abs.endsWith(".json")) return JSON.parse(readFileSync(abs, "utf8"));
@@ -68,9 +96,8 @@ function writeFindings(findings, stream) {
   for (const f of findings) {
     const severity = f.severity === "warning" ? "warning" : "error";
     const where = f.line ? ` line ${f.line}` : "";
-    stream.write(
-      `  ${severity} [${f.rule}]${where}: ${f.label}\n    ${f.snippet}\n`,
-    );
+    const snippet = f.snippet ? `    ${f.snippet}\n` : "";
+    stream.write(`  ${severity} [${f.rule}]${where}: ${f.label}\n${snippet}`);
   }
 }
 
@@ -104,16 +131,20 @@ async function runLint(rest) {
     }
   }
   const label = positionals.join(", ");
+  const assetsByDirectory = loadAssetsBesideFiles(Object.keys(files));
+  const assetsBeside = (filePath) =>
+    assetsByDirectory.get(bundledAssetDirectoryOf(dirname(filePath)));
   // Narrow per split-impl file, as the submission gate does.
   const perFile = Object.entries(files).map(([filePath, source]) => [
     filePath,
-    lintSource(
-      source,
-      manifest
+    lintSource(source, {
+      assetFiles: assetsBeside(filePath).fileNames,
+      ...(manifest
         ? { manifest: narrowManifestForFile(manifest, basename(filePath)) }
-        : undefined,
-    ),
+        : {}),
+    }),
   ]);
+  const bundled = [...assetsByDirectory.values()].flatMap(assetFindings);
   const wiring = manifest
     ? lintStyleWiring(manifest, files)
     : { ok: true, findings: [] };
@@ -123,6 +154,7 @@ async function runLint(rest) {
     : { ok: true, findings: [] };
   const all = perFile
     .flatMap(([, r]) => r.findings)
+    .concat(bundled)
     .concat(wiring.findings)
     .concat(editability.findings);
   if (all.length === 0) {
@@ -132,7 +164,11 @@ async function runLint(rest) {
   // sc-3493 — a warning-severity finding used to be swallowed: `ok` stays true
   // for warnings, so the CLI printed "clean" and dropped them. A warning nobody
   // sees is pointless. Report every finding; only errors change the exit code.
-  const ok = perFile.every(([, r]) => r.ok) && wiring.ok && editability.ok;
+  const ok =
+    perFile.every(([, r]) => r.ok) &&
+    bundled.length === 0 &&
+    wiring.ok &&
+    editability.ok;
   const errors = all.filter((f) => f.severity !== "warning").length;
   const stream = ok ? stdout : stderr;
   stream.write(
@@ -143,6 +179,10 @@ async function runLint(rest) {
     if (perFile.length > 1) stream.write(`${filePath}:\n`);
     writeFindings(r.findings, stream);
   }
+  if (bundled.length > 0) {
+    stream.write("assets:\n");
+    writeFindings(bundled, stream);
+  }
   if (wiring.findings.length > 0) {
     stream.write(`manifest.styleSchema:\n`);
     writeFindings(wiring.findings, stream);
@@ -185,7 +225,8 @@ async function runDev(rest) {
       `  manifest: ${handle.url}/manifest.json\n` +
       `  reload:   ${handle.url}/__dev/events (SSE)\n` +
       (handle.directoryMode
-        ? `  files:    ${handle.url}/file/<relpath>\n  shims:    ${handle.url}/shim/<slug>\n`
+        ? `  files:    ${handle.url}/file/<relpath>\n  shims:    ${handle.url}/shim/<slug>\n` +
+          `  assets:   ${handle.url}/assets/<name>\n`
         : "") +
       (handle.manifestId ? `  id:       ${handle.manifestId}\n` : "") +
       `\nIn the Studio Builder (dev mode), open the "Dev widgets" panel and add:\n` +

package/dist/contract.cjs

@@ -1171,6 +1171,20 @@ const HOOKS = [
     requiredContextSlice: ["assets.list"],
     scopes: null,
   },
+  {
+    name: "useBundledAsset",
+    signature: "useBundledAsset(fileName)",
+    description:
+      "Returns the URL of an image or sound file the widget package ships in " +
+      "its assets/ directory, or null when the package has no file with that " +
+      "name. Only an uploaded package can bundle files; a widget written in " +
+      "the Studio has none.",
+    returnShape: {
+      "(returns)": "string | null",
+    },
+    requiredContextSlice: ["widget.assets"],
+    scopes: null,
+  },
   {
     name: "useFilestoreFiles",
     signature: "useFilestoreFiles({ spaceType, recordId, folderId, q, type })",
@@ -2888,6 +2902,19 @@ const ACTION_SCRIPT_GLOBALS = [
 // Mirrors action.service.js SCRIPT_MAX_BYTES.
 const ACTION_SCRIPT_MAX_BYTES = 200 * 1024;
 
+// The one package size limit; the backend derives its upload caps from it.
+const PACKAGE_MAX_BYTES = 12 * 1024 * 1024;
+
+const BUNDLED_ASSETS = {
+  directory: "assets",
+  maxFiles: 50,
+  maxNameLength: 64,
+  types: {
+    image: { extensions: ["png", "jpg", "jpeg", "gif", "webp"] },
+    audio: { extensions: ["mp3", "m4a", "wav"] },
+  },
+};
+
 /**
  * sc-4915 — the trigger set a manifest action declares, canonically ordered.
  *
@@ -3071,9 +3098,15 @@ const WIDGET_CONTEXT_SHAPE = {
   },
   widget: {
     description:
-      "Identity of the currently rendered widget instance ({ id, version }).",
+      "Identity of the currently rendered widget instance ({ id, version }) " +
+      "and the files its package bundles.",
     required: true,
-    fields: { id: "manifest.id", version: "manifest.version" },
+    fields: {
+      id: "manifest.id",
+      version: "manifest.version",
+      assets:
+        "{ [fileName]: string } — bundled file name → absolute URL; {} when the package bundles nothing",
+    },
   },
   // REQ-LAY-08 — optional host layout hint backing useFill(). True when the
   // host sized this widget to fill its layout slot's available height (a
@@ -5268,7 +5301,11 @@ const CONTRACT = deepFreeze({
   //    asset carrying `durationMs`. New `useHardwareBack(handler)` walks a
   //    widget's own pages on Android's back button (optional
   //    `ctx.navigation.onHardwareBack`; unsupported on the web).
-  version: "1.158.0",
+  // 1.159.0: additive (sc-10721) — a package may ship images and sounds in a
+  //    flat `assets/` directory (`bundledAssets`, within `packageMaxBytes`).
+  //    New `useBundledAsset(fileName)` resolves one through the new
+  //    `widget.assets` map; linter rule `bundled-asset-missing` (error).
+  version: "1.159.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -5278,6 +5315,8 @@ const CONTRACT = deepFreeze({
   actionTriggerTypes: ACTION_TRIGGER_TYPES,
   actionScriptGlobals: ACTION_SCRIPT_GLOBALS,
   actionScriptMaxBytes: ACTION_SCRIPT_MAX_BYTES,
+  packageMaxBytes: PACKAGE_MAX_BYTES,
+  bundledAssets: BUNDLED_ASSETS,
   themeTokens: DEFAULT_THEME_TOKENS,
   themeColorTokens: THEME_COLOR_TOKENS,
   themeComponents: THEME_COMPONENTS,

package/dist/contract.js

@@ -1171,6 +1171,20 @@ const HOOKS = [
     requiredContextSlice: ["assets.list"],
     scopes: null,
   },
+  {
+    name: "useBundledAsset",
+    signature: "useBundledAsset(fileName)",
+    description:
+      "Returns the URL of an image or sound file the widget package ships in " +
+      "its assets/ directory, or null when the package has no file with that " +
+      "name. Only an uploaded package can bundle files; a widget written in " +
+      "the Studio has none.",
+    returnShape: {
+      "(returns)": "string | null",
+    },
+    requiredContextSlice: ["widget.assets"],
+    scopes: null,
+  },
   {
     name: "useFilestoreFiles",
     signature: "useFilestoreFiles({ spaceType, recordId, folderId, q, type })",
@@ -2884,6 +2898,19 @@ const ACTION_SCRIPT_GLOBALS = [
 // Mirrors action.service.js SCRIPT_MAX_BYTES.
 const ACTION_SCRIPT_MAX_BYTES = 200 * 1024;
 
+// The one package size limit; the backend derives its upload caps from it.
+const PACKAGE_MAX_BYTES = 12 * 1024 * 1024;
+
+const BUNDLED_ASSETS = {
+  directory: "assets",
+  maxFiles: 50,
+  maxNameLength: 64,
+  types: {
+    image: { extensions: ["png", "jpg", "jpeg", "gif", "webp"] },
+    audio: { extensions: ["mp3", "m4a", "wav"] },
+  },
+};
+
 /**
  * sc-4915 — the trigger set a manifest action declares, canonically ordered.
  *
@@ -3067,9 +3094,15 @@ const WIDGET_CONTEXT_SHAPE = {
   },
   widget: {
     description:
-      "Identity of the currently rendered widget instance ({ id, version }).",
+      "Identity of the currently rendered widget instance ({ id, version }) " +
+      "and the files its package bundles.",
     required: true,
-    fields: { id: "manifest.id", version: "manifest.version" },
+    fields: {
+      id: "manifest.id",
+      version: "manifest.version",
+      assets:
+        "{ [fileName]: string } — bundled file name → absolute URL; {} when the package bundles nothing",
+    },
   },
   // REQ-LAY-08 — optional host layout hint backing useFill(). True when the
   // host sized this widget to fill its layout slot's available height (a
@@ -5264,7 +5297,11 @@ const CONTRACT = deepFreeze({
   //    asset carrying `durationMs`. New `useHardwareBack(handler)` walks a
   //    widget's own pages on Android's back button (optional
   //    `ctx.navigation.onHardwareBack`; unsupported on the web).
-  version: "1.158.0",
+  // 1.159.0: additive (sc-10721) — a package may ship images and sounds in a
+  //    flat `assets/` directory (`bundledAssets`, within `packageMaxBytes`).
+  //    New `useBundledAsset(fileName)` resolves one through the new
+  //    `widget.assets` map; linter rule `bundled-asset-missing` (error).
+  version: "1.159.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -5274,6 +5311,8 @@ const CONTRACT = deepFreeze({
   actionTriggerTypes: ACTION_TRIGGER_TYPES,
   actionScriptGlobals: ACTION_SCRIPT_GLOBALS,
   actionScriptMaxBytes: ACTION_SCRIPT_MAX_BYTES,
+  packageMaxBytes: PACKAGE_MAX_BYTES,
+  bundledAssets: BUNDLED_ASSETS,
   themeTokens: DEFAULT_THEME_TOKENS,
   themeColorTokens: THEME_COLOR_TOKENS,
   themeComponents: THEME_COMPONENTS,

package/dist/devserver.js

@@ -24,8 +24,11 @@
 //       `globalThis.__appstudioWidgetHost__` — the same global the Studio's
 //       blob shims populate, so the dev path stays in lockstep with the
 //       published path;
+//     • serves the widget's bundled images and sounds at `/assets/<name>` and
+//       lists them at `/assets.json`;
 //     • watches the whole widget directory recursively for `.jsx`/`.json` and
-//       broadcasts `reload` to every connected client.
+//       anything under `assets/`, and broadcasts `reload` to every connected
+//       client.
 //
 //   single-file mode (legacy v1 — passed a bare `.jsx` entry)
 //     • original REQ-WSDK-DEVKIT behaviour. Kept so existing tasks don't
@@ -60,6 +63,15 @@ import {
 } from "node:fs";
 import { resolve, dirname, join, sep, relative, posix } from "node:path";
 import { lintSource } from "./linter.js";
+import {
+  BUNDLED_ASSET_DIRECTORY,
+  isValidBundledAssetName,
+  sniffBundledAssetType,
+} from "./bundled-assets.js";
+import {
+  bundledAssetDirectoryOf,
+  loadBundledAssets,
+} from "./bundled-assets-fs.js";
 import {
   getShimSource,
   shimmableSpecifiersForSiblings,
@@ -414,6 +426,16 @@ function _isUnderReal(parentRealAbs, childAbs) {
   }
 }
 
+const ASSET_ROUTE_PREFIX = `/${BUNDLED_ASSET_DIRECTORY}/`;
+const ASSET_PATH_RE = new RegExp(`^${BUNDLED_ASSET_DIRECTORY}[\\\\/]`);
+
+/** True when a change to `filename` (relative to the watch root) reloads. */
+export function isReloadTrigger(filename) {
+  if (!filename) return true;
+  const path = String(filename);
+  return /\.(jsx?|json)$/.test(path) || ASSET_PATH_RE.test(path);
+}
+
 function setCors(res) {
   res.setHeader("Access-Control-Allow-Origin", "*");
   res.setHeader("Access-Control-Allow-Methods", "GET, OPTIONS");
@@ -545,6 +567,35 @@ export function createDevServer({
     return { abs, rel: normalised };
   }
 
+  // Single-file mode has no widget directory, so it bundles nothing.
+  const assetsDir = directoryMode ? bundledAssetDirectoryOf(watchRoot) : null;
+  const bundledAssets = () => loadBundledAssets(assetsDir);
+
+  function serveAssetList(res) {
+    const names = bundledAssets().assets.map((asset) => asset.name);
+    res.writeHead(200, { "Content-Type": "application/json" });
+    res.end(JSON.stringify({ assets: names }));
+  }
+
+  function serveAsset(res, name) {
+    const resolved = isValidBundledAssetName(name)
+      ? resolveFileRel(`${BUNDLED_ASSET_DIRECTORY}/${name}`)
+      : null;
+    const bytes = resolved ? readFileSync(resolved.abs) : null;
+    const type = bytes ? sniffBundledAssetType(bytes) : null;
+    if (!type) {
+      res.writeHead(404, { "Content-Type": "text/plain" });
+      res.end("Bundled file not found");
+      return;
+    }
+    res.writeHead(200, {
+      "Content-Type": type.mimeType,
+      "Content-Length": bytes.length,
+      "Cache-Control": "no-store",
+    });
+    res.end(bytes);
+  }
+
   function transpileWithGuards(absPath) {
     const source = readFileSync(absPath, "utf8");
     try {
@@ -754,6 +805,10 @@ export function createDevServer({
       );
       return;
     }
+    if (url === "/assets.json") return serveAssetList(res);
+    if (url.startsWith(ASSET_ROUTE_PREFIX)) {
+      return serveAsset(res, url.slice(ASSET_ROUTE_PREFIX.length));
+    }
     if (directoryMode && url.startsWith("/file/")) {
       return serveFile(req, res, url.slice("/file/".length));
     }
@@ -782,15 +837,18 @@ export function createDevServer({
     } catch {
       return;
     }
-    const { ok, findings } = lintSource(source);
-    if (onLint) {
-      if (ok) onLint("lint: clean");
-      else {
-        onLint(`lint: ${findings.length} finding(s)`);
-        for (const f of findings)
-          onLint(`  [${f.rule}] line ${f.line}: ${f.label}`);
-      }
+    const assets = bundledAssets();
+    const { ok, findings } = lintSource(source, {
+      assetFiles: assets.fileNames,
+    });
+    if (!onLint) return;
+    if (ok && assets.ok) {
+      onLint("lint: clean");
+      return;
     }
+    onLint(`lint: ${findings.length + assets.errors.length} finding(s)`);
+    for (const e of assets.errors) onLint(`  [${e.code}] ${e.message}`);
+    for (const f of findings) onLint(`  [${f.rule}] line ${f.line}: ${f.label}`);
   }
 
   return {
@@ -939,7 +997,7 @@ export async function startDevServer({
     dev.watchRoot,
     { recursive: directoryMode },
     (_event, filename) => {
-      if (filename && !/\.(jsx?|json)$/.test(String(filename))) return;
+      if (!isReloadTrigger(filename)) return;
       if (timer) clearTimeout(timer);
       timer = setTimeout(() => {
         timer = null;

package/dist/emoji-picker.js

@@ -10,5 +10,6 @@
 import * as ReactNative from "react-native-web";
 import { makeEmojiPicker } from "./emoji-picker-view.js";
 import { Overlay } from "./overlay.js";
+import { TextInput } from "./primitives.js";
 
-export const EmojiPicker = makeEmojiPicker({ ...ReactNative, Overlay });
+export const EmojiPicker = makeEmojiPicker({ ...ReactNative, TextInput, Overlay });

package/dist/hooks.js

@@ -4334,6 +4334,20 @@ export function useAsset(assetId) {
   return { url, asset, loading, error, refetch };
 }
 
+/**
+ * URL of a file the widget package ships in its `assets/` directory, or
+ * `null` when the package bundles no file with that name.
+ */
+export function useBundledAsset(fileName) {
+  const ctx = useWidgetContextOrThrow("useBundledAsset");
+  // An older host publishes no `widget.assets`.
+  const assets = ctx.widget && ctx.widget.assets;
+  if (!fileName || !assets) return null;
+  return Object.prototype.hasOwnProperty.call(assets, fileName)
+    ? assets[fileName]
+    : null;
+}
+
 /**
  * List every tenant asset carrying a given tag. Returns
  * `{ assets, loading, error, refetch }`. The widget passes a single `tag`

package/dist/host.d.ts

@@ -460,6 +460,12 @@ export interface LoginDesign {
 /** The sign-in screen's authored design, or null when nothing is configured. */
 export function normaliseLoginDesign(raw: unknown): LoginDesign | null;
 
+/** sc-10845 — the sign-in card's logo: the author's own, else the app logo. */
+export function resolveLoginLogoUrl(
+  login: unknown,
+  appLogoUrl: string | null | undefined,
+): string | null;
+
 /** sc-7800 — true when a stored value is a `theme:<path>` colour binding. */
 export function isThemeTokenRef(value: unknown): boolean;
 

package/dist/host.js

@@ -128,6 +128,7 @@ export {
   LOGIN_TEXT_MAX_LENGTH,
   normaliseThemeGradient,
   normaliseLoginDesign,
+  resolveLoginLogoUrl,
 } from "./theme-background.js";
 
 // sc-8448: one DATETIME local-clock conversion for the picker and the Studio.

package/dist/index.d.ts

@@ -698,7 +698,13 @@ export interface RecordMuteWire {
 
 export interface WidgetContext<TProps = unknown> {
   props: TProps;
-  widget: { id: string; instanceId: string; version: string };
+  widget: {
+    id: string;
+    instanceId: string;
+    version: string;
+    /** Bundled file name → absolute URL; `{}` when the package bundles nothing. */
+    assets: Record<string, string>;
+  };
   /**
    * REQ-LAY-08 — optional host layout hint backing `useFill()`. `true` when
    * the host sized this widget to fill its layout slot's available height (a
@@ -1614,6 +1620,18 @@ export function useAsset(assetId: string | null | undefined): {
   refetch(): Promise<void>;
 };
 
+/**
+ * URL of an image or sound file the widget package ships in its `assets/`
+ * directory, or `null` when the package has no file with that name.
+ *
+ * ```jsx
+ * const logo = useBundledAsset("logo.png");
+ * const chime = useAudioPlayer(useBundledAsset("chime.mp3"));
+ * return logo ? <Image source={{ uri: logo }} /> : null;
+ * ```
+ */
+export function useBundledAsset(fileName: string | null | undefined): string | null;
+
 /**
  * List every tenant asset carrying a given tag. Reads `ctx.assets.list({
  * tag, type, limit })` and unwraps the `{ data, meta }` envelope.
@@ -3705,6 +3723,12 @@ export interface LintFinding {
 }
 export interface LintOptions {
   manifest?: { requestedScopes?: string[]; supportedPlatforms?: string[] };
+  /**
+   * File names in the package's `assets/` directory. When given, a
+   * `useBundledAsset("name")` literal naming a file outside the list is a
+   * `bundled-asset-missing` error; omit it to skip that rule.
+   */
+  assetFiles?: string[];
 }
 export function lintSource(
   source: string,
@@ -3714,6 +3738,40 @@ export function lintSource(
   findings: LintFinding[];
 };
 
+// Bundled assets — the files a package ships in its `assets/` directory.
+export type BundledAssetKind = "image" | "audio";
+export type BundledAssetErrorCode =
+  | "ASSET_NAME_INVALID"
+  | "ASSET_TYPE_NOT_ALLOWED"
+  | "ASSET_EMPTY"
+  | "ASSET_CONTENT_MISMATCH"
+  | "ASSET_NAME_DUPLICATE"
+  | "ASSET_TOO_MANY";
+export interface BundledAssetError {
+  code: BundledAssetErrorCode;
+  /** `null` for an error about the directory as a whole (`ASSET_TOO_MANY`). */
+  name: string | null;
+  message: string;
+}
+export interface BundledAsset {
+  name: string;
+  kind: BundledAssetKind;
+  mimeType: string;
+  sizeBytes: number;
+}
+/** The package directory bundled files live in (`"assets"`); from the `./bundled-assets` entry. */
+export const BUNDLED_ASSET_DIRECTORY: string;
+/** True when `name` may be used as a file name inside `assets/`. */
+export function isValidBundledAssetName(name: unknown): boolean;
+/** Identifies a bundled file from its leading bytes; `null` when it is not an allowed type. */
+export function sniffBundledAssetType(
+  bytes: Uint8Array,
+): { kind: BundledAssetKind; mimeType: string; extensions: string[] } | null;
+/** Validates the files of an `assets/` directory; `assets` is sorted by name. */
+export function validateBundledAssets(
+  files: Array<{ name: string; bytes: Uint8Array }>,
+): { ok: boolean; errors: BundledAssetError[]; assets: BundledAsset[] };
+
 // --------------------------------------------------------------- CONTRACT
 //
 // Single-source-of-truth contract artefact. See docs/design/ai-widget-contract.md.
@@ -3768,6 +3826,17 @@ export interface AiWidgetContract {
   readonly manifestSchema: Readonly<Record<string, ContractManifestField>>;
   readonly manifestCategories: ReadonlyArray<string>;
   readonly manifestPlatforms: ReadonlyArray<string>;
+  /** Largest package a widget may ship, bundled files included. */
+  readonly packageMaxBytes: number;
+  /** What a package may ship in its `assets/` directory. */
+  readonly bundledAssets: {
+    readonly directory: string;
+    readonly maxFiles: number;
+    readonly maxNameLength: number;
+    readonly types: Readonly<
+      Record<BundledAssetKind, { readonly extensions: ReadonlyArray<string> }>
+    >;
+  };
   readonly themeTokens: ThemeTokens;
   /** sc-7800 — the brand colour tokens a `type: "color"` field may bind to. */
   readonly themeColorTokens: ReadonlyArray<{ path: string; label: string }>;

package/dist/index.js

@@ -39,6 +39,7 @@ export {
   useAgent,
   useAsset,
   useAssetsByTag,
+  useBundledAsset,
   useFilestoreFiles,
   useFilestoreFile,
   useFilestoreUpload,
@@ -169,6 +170,11 @@ export {
   Video,
 } from "./primitives.js";
 export { lintSource, bannedIdentifiers } from "./linter.js";
+export {
+  validateBundledAssets,
+  sniffBundledAssetType,
+  isValidBundledAssetName,
+} from "./bundled-assets.js";
 // sc-3696: the trailing six are the theme-derivation helpers both hosts resolve
 // `useTheme()` with (the Player through widgetTheme.js, the export through its
 // generated theme module), plus the gradient angle projection `<Gradient>`

package/dist/index.native.js

@@ -39,6 +39,7 @@ export {
   useAgent,
   useAsset,
   useAssetsByTag,
+  useBundledAsset,
   useFilestoreFiles,
   useFilestoreFile,
   useFilestoreUpload,
@@ -162,6 +163,11 @@ export {
   Video,
 } from "./primitives.native.js";
 export { lintSource, bannedIdentifiers } from "./linter.js";
+export {
+  validateBundledAssets,
+  sniffBundledAssetType,
+  isValidBundledAssetName,
+} from "./bundled-assets.js";
 // sc-3696: the trailing six are the theme-derivation helpers both hosts resolve
 // `useTheme()` with (the Player through widgetTheme.js, the export through its
 // generated theme module), plus the gradient angle projection `<Gradient>`

package/dist/linter.cjs

@@ -1082,6 +1082,33 @@ function _jsxOpenTagEnd(source, from) {
   return source.length;
 }
 
+// sc-10721 — a useBundledAsset literal must name a file the package ships.
+const BUNDLED_ASSET_CALL_RE =
+  /\buseBundledAsset\s*\(\s*(?:"([^"\n]*)"|'([^'\n]*)'|`([^`]*)`)\s*[,)]/g;
+
+function _bundledAssetRules(source, assetFiles) {
+  if (!Array.isArray(assetFiles)) return [];
+  const findings = [];
+  // Comments blanked, strings kept: the file name IS a string literal.
+  const code = _stripNonCode(source, { keepStrings: true });
+  const sourceLines = source.split(/\r?\n/);
+  for (const match of code.matchAll(BUNDLED_ASSET_CALL_RE)) {
+    const name = match[1] || match[2] || match[3] || "";
+    if (name.includes("${") || assetFiles.includes(name)) continue;
+    const line = code.slice(0, match.index).split(/\r?\n/).length;
+    findings.push({
+      rule: "bundled-asset-missing",
+      severity: "error",
+      label:
+        `useBundledAsset("${name}") names a file that is not in the package's ` +
+        "assets/ directory. Add the file there or correct the name.",
+      line,
+      snippet: (sourceLines[line - 1] || "").trim().slice(0, 200),
+    });
+  }
+  return findings;
+}
+
 // sc-4649 / sc-4686 — see linter.js for the rationale comments. The two
 // files must stay in lockstep (a test asserts behaviour-equivalence).
 const REQUEST_PAYMENT_CALL = "requestPayment(";
@@ -2015,6 +2042,7 @@ function lintSource(source, options) {
   findings.push(..._translationApiRules(source));
   findings.push(..._handBuiltPageUrlRules(source));
   findings.push(..._lucideIconRules(source));
+  findings.push(..._bundledAssetRules(source, options && options.assetFiles));
   findings.push(..._selfContainedReferenceRules(source));
   findings.push(..._imagePercentHeightRules(source));
   // sc-7274 — soft warning: a percentage flexBasis sizes the main axis, so in a