@colixsystems/widget-sdk 0.198.0 → 0.199.0

package/README.md

@@ -9,6 +9,7 @@ The data layer lives in **four separate domain-client packages**, each instantia
 | `ctx.datastore` | `@colixsystems/datastore-client` | `tables.{list,get}`, `schema(tableId)`, `myPermissions(tableId, { recordId? })`, `records(tableId).{ list(query), get(id), create(values), update(id,values) [PATCH], delete(id), aggregate(spec), permissions(recordId).{ list, grant, update, revoke } }` |
 | `ctx.directory` | `@colixsystems/directory-client` | `me()`, `users.{list,get,invite,deactivate,reactivate}`, `groups.{list,create,remove,addMember,removeMember,listMine}`, `invites.{list,revoke,resend}` |
 | `ctx.assets` | `@colixsystems/assets-client` | the Asset Manager: `get(id)`, `list(query)`, `upload(formData)` over `/files` — what `useAsset()` (single asset by id) and `useAssetsByTag()` (every asset carrying a tag) resolve |
+| `ctx.widget.assets` | — (built by the host) | the files the widget package bundles: a map of file name → absolute URL, `{}` when it bundles nothing — what `useBundledAsset()` resolves |
 | `ctx.payments` | `@colixsystems/payments-client` | `requestPayment(body)`, `getPayment(id)` |
 
 **Wire / casing: snake_case end to end.** The clients send and return snake_case **verbatim** (`created_at`, `group_ids`, `can_read`, `amount_cents`, `data_type`, `is_active`, …). There is **no case transform anywhere** — not on the client and not in the backend; the only casing boundary is Prisma `@map` (snake_case field → camelCase column). Author-defined record column values pass through verbatim. Every `list(...)` returns the `{ data, meta }` envelope; the read hooks unwrap `res.data` for you.
@@ -59,8 +60,9 @@ The data layer lives in **four separate domain-client packages**, each instantia
 | **DATASTORE** | `useTyping(tableId, recordId)` | `{ typingUserIds, setTyping, status }` — status `"connecting" \| "live" \| "unavailable"` | `records(table).typing` — `datastore.read:<table>`. Who else is typing in one record, over the same socket as `useDatastoreSubscription`. Call `setTyping(true)` on every keystroke (throttled to one signal per 3 s; `false` is sent after 5 s idle) and `setTyping(false)` on send, clear or blur. `typingUserIds` lists the OTHER users' ids; each drops out 6 s after their last signal. Needs a signed-in user who can read the record. Never throws: an anonymous visitor, a refused subscription or a host whose client lacks `typing` reads `{ typingUserIds: [], status: "unavailable" }`. Re-subscribes when either id changes. |
 | **DATASTORE** | `useRecordPermissions(tableId, recordId)` | `{ permissions, loading, error, grant, revoke, update, refetch }` | `records(table).permissions(record).{ list, grant, update, revoke }` — `acl.write:records` (+ `can_grant` on the record) |
 | **DATASTORE** | `useCanWrite(tableId, options)` (optional: options) | `{ canWrite, loading, error, refetch }` | `myPermissions(tableId, { recordId? })` — scope `datastore.read:<table>`. A FLOOR, not a full replacement for domain-specific write rules: answers "may this caller write", reading the same table-ACL answer the write endpoint enforces — so a table granting Create to Everyone answers `true` for a logged-out visitor, and this hook alone is the right gate for a widget meant to work without signing in. Pass `{ recordId }` for a per-row check. A widget whose own rule is MORE SPECIFIC than the table ACL (e.g. "only the assigned user may edit this row") must still hand-check that in addition. Pair with `useUser()` to also tell "not signed in" apart from "signed in but forbidden" — both resolve `canWrite: false` here. Falsy `tableId`, or a host that hasn't injected `myPermissions` (an older host), collapses to `{ canWrite: false, loading: false, error: null, refetch: async () => undefined }` rather than throwing. |
-| **FILES** (`ctx.assets`) | `useAsset(id)` | `{ url, file, loading, error, refetch }` | `ctx.assets.get` — no scope |
+| **FILES** (`ctx.assets`) | `useAsset(id)` | `{ url, asset, loading, error, refetch }` | `ctx.assets.get` — no scope |
 | **FILES** | `useAssetsByTag(tag, { type })` (optional: the whole argument, and `type` within it) | `{ assets, loading, error, refetch }` | `ctx.assets.list` (unwraps `{ data, meta }` to `assets`) — no scope. `type` defaults to `"image"`; pass `"all"` / `"audio"` / `"video"` / `"document"` to widen. Falsy `tag` collapses to `assets: []` without a round-trip. |
+| **FILES** (`ctx.widget`) | `useBundledAsset(fileName)` | `string \| null` | `ctx.widget.assets` — no scope. The URL of an image or sound the widget package ships in its `assets/` directory, or `null` when it has no file with that name. See [Bundled images and sounds](#bundled-images-and-sounds). |
 | **DIRECTORY** (`ctx.directory`) | `useDirectory(query)` (optional: query) | `{ users, loading, error, refetch }` | `directory.users.list` — `directory.read:users` |
 | **DIRECTORY** | `useUsers(query)` (optional: query) | `{ users, loading, error, refetch, invite, deactivate, reactivate, remove, sendPasswordReset, update }` | `directory.users.*` — `users.read:*` plus the `users.read` (or `users.write`) capability, else `FORBIDDEN` (edits, incl. `sendPasswordReset()` and `update()`, also `users.write:*`; `remove()` also `users.delete:*`) |
 | **DIRECTORY** | `useGroups(query)` (optional: query) | `{ groups, loading, error, refetch, create, remove, addMember, removeMember }` | `directory.groups.*` — `groups.read:*` (mutations also `groups.write:*`) |
@@ -81,8 +83,29 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.198.0` — pre-publish. The package surface (types, function names, export paths) is the v1 contract; runtime behaviour for some hooks is stubbed (each hook documents what's wired and what isn't). It is **not yet published to npm**.
+`v0.199.0` — pre-publish. The package surface (types, function names, export paths) is the v1 contract; runtime behaviour for some hooks is stubbed (each hook documents what's wired and what isn't). It is **not yet published to npm**.
 
+### What's new in 0.199.0 (contract 1.159.0)
+
+**A widget package can bundle its own images and sounds — `assets/` + `useBundledAsset(fileName)`.** Files in a flat `assets/` directory ship with the package, and the new hook returns each one's URL on web and native alike:
+
+```jsx
+import { Image, useAudioPlayer, useBundledAsset } from "@colixsystems/widget-sdk";
+
+function Welcome() {
+  const logo = useBundledAsset("logo.png");
+  const chime = useAudioPlayer(useBundledAsset("chime.mp3"));
+  return logo ? <Image source={{ uri: logo }} style={{ width: 96, height: 96 }} /> : null;
+}
+```
+
+- **Allowed:** `png`, `jpg`, `jpeg`, `gif`, `webp`, `mp3`, `m4a` and `wav`; at most 50 files; the whole package at most 12 MB. The rules are published as `CONTRACT.bundledAssets` and `CONTRACT.packageMaxBytes`.
+- **`ctx.widget.assets`** is the map the hook reads: bundled file name → absolute URL, `{}` when the package bundles nothing. A host that predates it publishes no map, and the hook returns `null`.
+- **New linter rule `bundled-asset-missing` (error).** With the new `assetFiles` option, `lintSource` flags a `useBundledAsset("name")` literal naming a file the package does not ship. `appstudio-widget lint` passes the option itself and also validates every file in `assets/`.
+- **New exports** `validateBundledAssets`, `sniffBundledAssetType` and `isValidBundledAssetName`, from the package root and from `@colixsystems/widget-sdk/bundled-assets` (ESM and CommonJS).
+- **`appstudio-widget dev`** serves a widget directory's files at `/assets/<name>`, lists them at `/assets.json`, and reloads when one changes.
+
+See [Bundled images and sounds](#bundled-images-and-sounds). Additive: a widget with no `assets/` directory is unaffected.
 ### What's new in 0.198.0 (contract 1.158.0)
 
 **`manifest.translations` may declare up to 200 keys (was 100).** A messenger or a form builder outgrows 100 strings once it ships every label its users read. Widening: every manifest that validated before still does.
@@ -2596,6 +2619,70 @@ native-only package while claiming web (or vice-versa) fails the
 platform, or ship the split pair. So you can't accidentally publish a widget
 that renders on one platform and blanks on the other.
 
+## Bundled images and sounds
+
+A widget package can ship its own images and sounds, so a logo, an illustration or a notification chime travels with the widget instead of being uploaded to every workspace by hand. Put the files in an `assets/` directory at the package root and list it in `package.json`'s `files`:
+
+```
+my-widget/
+├── package.json     "files": ["widget.jsx", "appstudio.manifest.json", "assets"]
+├── manifest.js
+├── widget.jsx
+└── assets/
+    ├── logo.png
+    └── chime.mp3
+```
+
+The rules are published as `CONTRACT.bundledAssets` and `CONTRACT.packageMaxBytes`:
+
+| Rule | Value |
+| ---- | ----- |
+| Images | `png`, `jpg`, `jpeg`, `gif`, `webp` |
+| Sounds | `mp3`, `m4a`, `wav` |
+| Layout | one flat `assets/` directory — no subdirectories |
+| File name | starts with a letter or digit; letters, digits, `.`, `-` and `_` only; at most 64 characters; unique ignoring case |
+| Files | at most 50 |
+| Package size | at most 12 MB for the whole package, bundled files included |
+
+A file must really be the type its extension says: the content is checked, so a renamed `.svg` or `.bmp` is refused.
+
+Read a file with `useBundledAsset(fileName)`. It returns an absolute URL on both the web Player and the native app, or `null` when the package has no file with that name:
+
+```jsx
+import {
+  Image,
+  Pressable,
+  Text,
+  useAudioPlayer,
+  useBundledAsset,
+} from "@colixsystems/widget-sdk";
+
+export default function Welcome() {
+  const logo = useBundledAsset("logo.png");
+  const chime = useAudioPlayer(useBundledAsset("chime.mp3"));
+  return (
+    <Pressable onPress={() => chime.play()}>
+      {logo ? <Image source={{ uri: logo }} style={{ width: 96, height: 96 }} /> : null}
+      <Text>Tap to play</Text>
+    </Pressable>
+  );
+}
+```
+
+Only an uploaded package can bundle files. A widget written in the Studio has none, so `useBundledAsset` returns `null` there; use `useAsset` / `useAssetsByTag` for files a workspace uploads itself. When a workspace installs the widget, its bundled files also appear in that workspace's assets.
+
+`appstudio-widget lint` checks an `assets/` directory beside each file it lints. A file that may not be bundled is an error named by its code (`ASSET_NAME_INVALID`, `ASSET_TYPE_NOT_ALLOWED`, `ASSET_EMPTY`, `ASSET_CONTENT_MISMATCH`, `ASSET_NAME_DUPLICATE`, `ASSET_TOO_MANY`), and the linter rule **`bundled-asset-missing`** (error) flags a `useBundledAsset("name")` literal that names a file the directory does not contain. A name built at runtime is not checked. The same checks are available as functions:
+
+```js
+import { lintSource } from "@colixsystems/widget-sdk/linter";
+import { validateBundledAssets } from "@colixsystems/widget-sdk/bundled-assets";
+
+const { ok, errors, assets } = validateBundledAssets([{ name: "logo.png", bytes }]);
+const report = lintSource(source, { assetFiles: assets.map((a) => a.name) });
+```
+
+`validateBundledAssets(files)` returns `{ ok, errors: [{ code, name, message }], assets: [{ name, kind, mimeType, sizeBytes }] }`. `sniffBundledAssetType(bytes)` identifies one file from its leading bytes and `isValidBundledAssetName(name)` checks one name. Omit `assetFiles` and `lintSource` skips `bundled-asset-missing`.
+
 ## Linter
 
 ```sh
@@ -2645,7 +2732,9 @@ and serves it over `http://127.0.0.1:4400`:
 | ----- | ------- |
 | `GET /widget.mjs` | the transpiled entry — an ES module the Studio loads exactly like a published `widget.mjs` |
 | `GET /manifest.json` | the manifest (from `--manifest`, else a sibling `manifest.json`); only consulted for a bare-component bundle |
-| `GET /__dev/events` | Server-Sent-Events stream that emits `reload` on every source change |
+| `GET /assets/<name>` | a bundled image or sound from the widget directory's `assets/` (directory mode) |
+| `GET /assets.json` | `{ assets }` — the names of the valid bundled files, sorted |
+| `GET /__dev/events` | Server-Sent-Events stream that emits `reload` on every source change, and on every change under `assets/` |
 | `GET /__dev/health` | `{ ok, manifestId }` |
 
 Then, in the Studio Builder (dev mode only), open the **Dev widgets** panel in

package/dist/bundled-assets-fs.js

@@ -0,0 +1,60 @@
+// Reads a package's assets/ directory from disk for the Node-side tools (the
+// CLI, the dev server, the first-party packer). The rules themselves live in
+// bundled-assets.js, which stays filesystem-free.
+
+import { lstatSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import {
+  BUNDLED_ASSET_DIRECTORY,
+  validateBundledAssets,
+} from "./bundled-assets.js";
+
+const NO_BYTES = new Uint8Array(0);
+
+// npm pack never ships these, so they are not part of the package.
+function _isOsMetadata(name) {
+  return name === ".DS_Store" || name.startsWith("._");
+}
+
+function _isRealDirectory(path) {
+  if (!path) return false;
+  try {
+    return lstatSync(path).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+function _readEntry(assetsDir, entry) {
+  const absPath = join(assetsDir, entry.name);
+  // A trailing slash makes the validator refuse the subdirectory by name.
+  if (entry.isDirectory()) return { name: `${entry.name}/`, absPath, bytes: NO_BYTES };
+  return { name: entry.name, absPath, bytes: readFileSync(absPath) };
+}
+
+/** Path of the assets/ directory that sits beside a widget's source. */
+export function bundledAssetDirectoryOf(ownerDir) {
+  return join(ownerDir, BUNDLED_ASSET_DIRECTORY);
+}
+
+/**
+ * Read and validate one assets/ directory (non-recursive). Links are never
+ * followed: a linked directory reads as absent and a linked file is skipped.
+ *
+ * Returns the `validateBundledAssets` result plus `files`
+ * (`[{ name, absPath, bytes }]`) and `fileNames` (the regular files present,
+ * valid or not). A missing directory, or no path, is an empty, valid result.
+ */
+export function loadBundledAssets(assetsDir) {
+  const files = _isRealDirectory(assetsDir)
+    ? readdirSync(assetsDir, { withFileTypes: true })
+        .filter((entry) => entry.isFile() || entry.isDirectory())
+        .filter((entry) => !_isOsMetadata(entry.name))
+        .map((entry) => _readEntry(assetsDir, entry))
+        .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))
+    : [];
+  const fileNames = files
+    .filter((file) => !file.name.endsWith("/"))
+    .map((file) => file.name);
+  return { files, fileNames, ...validateBundledAssets(files) };
+}

package/dist/bundled-assets.cjs

@@ -0,0 +1,239 @@
+// The files a widget package ships in its assets/ directory: which names and
+// types are allowed. Pure and filesystem-free, so the CLI, the dev server, the
+// first-party packer and the backend all apply one rule set.
+// CommonJS twin of bundled-assets.js for the backend. Keep both in lockstep.
+
+const { CONTRACT } = require("./contract.cjs");
+
+const RULES = CONTRACT.bundledAssets;
+const BUNDLED_ASSET_DIRECTORY = RULES.directory;
+const ALLOWED_EXTENSIONS = Object.values(RULES.types).flatMap(
+  (type) => type.extensions,
+);
+const NAME_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+
+const PNG = { kind: "image", mimeType: "image/png", extensions: ["png"] };
+const JPEG = { kind: "image", mimeType: "image/jpeg", extensions: ["jpg", "jpeg"] };
+const GIF = { kind: "image", mimeType: "image/gif", extensions: ["gif"] };
+const WEBP = { kind: "image", mimeType: "image/webp", extensions: ["webp"] };
+const WAV = { kind: "audio", mimeType: "audio/wav", extensions: ["wav"] };
+const MP3 = { kind: "audio", mimeType: "audio/mpeg", extensions: ["mp3"] };
+const M4A = { kind: "audio", mimeType: "audio/mp4", extensions: ["m4a"] };
+
+const PNG_SIGNATURE = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a];
+const JPEG_SIGNATURE = [0xff, 0xd8, 0xff];
+const M4A_BRANDS = ["M4A ", "M4B ", "mp42", "isom", "mp41"];
+
+function _hasBytes(bytes, signature, offset) {
+  if (bytes.length < offset + signature.length) return false;
+  return signature.every((byte, i) => bytes[offset + i] === byte);
+}
+
+function _hasText(bytes, text, offset) {
+  return _hasBytes(bytes, Array.from(text, (ch) => ch.charCodeAt(0)), offset);
+}
+
+// kbps by bitrate index; index 0 (free format) and 15 are never accepted.
+const MPEG_BITRATES = {
+  v1Layer1: [0, 32, 64, 96, 128, 160, 192, 224, 256, 288, 320, 352, 384, 416, 448],
+  v1Layer2: [0, 32, 48, 56, 64, 80, 96, 112, 128, 160, 192, 224, 256, 320, 384],
+  v1Layer3: [0, 32, 40, 48, 56, 64, 80, 96, 112, 128, 160, 192, 224, 256, 320],
+  v2Layer1: [0, 32, 48, 56, 64, 80, 96, 112, 128, 144, 160, 176, 192, 224, 256],
+  v2Layer2or3: [0, 8, 16, 24, 32, 40, 48, 56, 64, 80, 96, 112, 128, 144, 160],
+};
+// Hz by the header's version bits (3 = MPEG-1, 2 = MPEG-2, 0 = MPEG-2.5).
+const MPEG_SAMPLE_RATES = {
+  3: [44100, 48000, 32000],
+  2: [22050, 24000, 16000],
+  0: [11025, 12000, 8000],
+};
+const MPEG_LAYER_1 = 3;
+const MPEG_LAYER_3 = 1;
+
+function _mpegBitrateTable(isVersion1, layer) {
+  if (layer === MPEG_LAYER_1) return isVersion1 ? MPEG_BITRATES.v1Layer1 : MPEG_BITRATES.v2Layer1;
+  if (!isVersion1) return MPEG_BITRATES.v2Layer2or3;
+  return layer === MPEG_LAYER_3 ? MPEG_BITRATES.v1Layer3 : MPEG_BITRATES.v1Layer2;
+}
+
+/** Byte length of the MPEG audio frame whose header starts at `offset`, or 0. */
+function _mpegFrameLength(bytes, offset) {
+  if (bytes.length < offset + 4) return 0;
+  if (bytes[offset] !== 0xff || (bytes[offset + 1] & 0xe0) !== 0xe0) return 0;
+  const version = (bytes[offset + 1] >> 3) & 3;
+  const layer = (bytes[offset + 1] >> 1) & 3;
+  const bitrateIndex = bytes[offset + 2] >> 4;
+  const sampleRateIndex = (bytes[offset + 2] >> 2) & 3;
+  const padding = (bytes[offset + 2] >> 1) & 1;
+  if (version === 1 || layer === 0 || sampleRateIndex === 3) return 0;
+  if (bitrateIndex === 0 || bitrateIndex === 15) return 0;
+  const isVersion1 = version === 3;
+  const bitrate = _mpegBitrateTable(isVersion1, layer)[bitrateIndex] * 1000;
+  const sampleRate = MPEG_SAMPLE_RATES[version][sampleRateIndex];
+  if (layer === MPEG_LAYER_1) return (Math.floor((12 * bitrate) / sampleRate) + padding) * 4;
+  const samplesPerByte = layer === MPEG_LAYER_3 && !isVersion1 ? 72 : 144;
+  return Math.floor((samplesPerByte * bitrate) / sampleRate) + padding;
+}
+
+// A two-byte sync alone matches a UTF-16 BOM, so a second frame must follow.
+function _isMpegAudioAt(bytes, offset) {
+  const length = _mpegFrameLength(bytes, offset);
+  if (length === 0) return false;
+  const next = offset + length;
+  return next === bytes.length || _mpegFrameLength(bytes, next) > 0;
+}
+
+const ID3_HEADER_BYTES = 10;
+
+function _isMp3(bytes) {
+  if (!_hasText(bytes, "ID3", 0)) return _isMpegAudioAt(bytes, 0);
+  if (bytes.length < ID3_HEADER_BYTES || bytes[3] === 0xff || bytes[4] === 0xff) return false;
+  const size = [bytes[6], bytes[7], bytes[8], bytes[9]];
+  if (size.some((byte) => byte >= 0x80)) return false;
+  const tagBytes = (size[0] << 21) | (size[1] << 14) | (size[2] << 7) | size[3];
+  const footerBytes = bytes[5] & 0x10 ? ID3_HEADER_BYTES : 0;
+  return _isMpegAudioAt(bytes, ID3_HEADER_BYTES + tagBytes + footerBytes);
+}
+
+function _describe(type) {
+  return { kind: type.kind, mimeType: type.mimeType, extensions: [...type.extensions] };
+}
+
+function _sniff(bytes) {
+  if (_hasBytes(bytes, PNG_SIGNATURE, 0)) return PNG;
+  if (_hasBytes(bytes, JPEG_SIGNATURE, 0)) return JPEG;
+  if (_hasText(bytes, "GIF87a", 0) || _hasText(bytes, "GIF89a", 0)) return GIF;
+  if (_hasText(bytes, "RIFF", 0)) {
+    if (_hasText(bytes, "WEBP", 8)) return WEBP;
+    if (_hasText(bytes, "WAVE", 8)) return WAV;
+    return null;
+  }
+  if (_hasText(bytes, "ftyp", 4)) {
+    return M4A_BRANDS.some((brand) => _hasText(bytes, brand, 8)) ? M4A : null;
+  }
+  if (_isMp3(bytes)) return MP3;
+  return null;
+}
+
+/**
+ * Identify a bundled file from its leading bytes alone.
+ * Returns `{ kind: "image" | "audio", mimeType, extensions }`, or `null` when
+ * the bytes are not one of the bundled types.
+ */
+function sniffBundledAssetType(bytes) {
+  if (!bytes || typeof bytes.length !== "number") return null;
+  const type = _sniff(bytes);
+  return type ? _describe(type) : null;
+}
+
+function _extensionOf(name) {
+  const dot = name.lastIndexOf(".");
+  return dot === -1 ? "" : name.slice(dot + 1).toLowerCase();
+}
+
+function _isWellFormedName(name) {
+  return (
+    typeof name === "string" &&
+    name.length <= RULES.maxNameLength &&
+    NAME_RE.test(name) &&
+    !name.includes("..")
+  );
+}
+
+/** True when `name` may be used as a file name inside a package's assets/. */
+function isValidBundledAssetName(name) {
+  return _isWellFormedName(name) && ALLOWED_EXTENSIONS.includes(_extensionOf(name));
+}
+
+function _extensionList() {
+  const last = ALLOWED_EXTENSIONS[ALLOWED_EXTENSIONS.length - 1];
+  return `${ALLOWED_EXTENSIONS.slice(0, -1).join(", ")} and ${last}`;
+}
+
+function _error(code, name, rule) {
+  const where = `${BUNDLED_ASSET_DIRECTORY}/${name === null ? "" : name}`;
+  return { code, name, message: `${where}: ${rule}` };
+}
+
+function _fileError(file, seenNames) {
+  const { name, bytes } = file;
+  if (!_isWellFormedName(name)) {
+    return _error(
+      "ASSET_NAME_INVALID",
+      typeof name === "string" ? name : String(name),
+      "a bundled file name starts with a letter or digit, uses only letters, " +
+        `digits, dots, hyphens and underscores, and is at most ${RULES.maxNameLength} ` +
+        "characters long. Subdirectories are not allowed.",
+    );
+  }
+  const extension = _extensionOf(name);
+  if (!ALLOWED_EXTENSIONS.includes(extension)) {
+    return _error(
+      "ASSET_TYPE_NOT_ALLOWED",
+      name,
+      `only ${_extensionList()} files can be bundled.`,
+    );
+  }
+  if (seenNames.has(name.toLowerCase())) {
+    return _error(
+      "ASSET_NAME_DUPLICATE",
+      name,
+      "another bundled file has the same name when upper and lower case are ignored.",
+    );
+  }
+  seenNames.add(name.toLowerCase());
+  if (!bytes || !bytes.length) {
+    return _error("ASSET_EMPTY", name, "the file is empty.");
+  }
+  const sniffed = _sniff(bytes);
+  if (!sniffed || !sniffed.extensions.includes(extension)) {
+    return _error(
+      "ASSET_CONTENT_MISMATCH",
+      name,
+      `the file's content is not a valid .${extension} file.`,
+    );
+  }
+  return null;
+}
+
+/**
+ * Validate the files of a package's assets/ directory.
+ * `files` is `[{ name, bytes }]`. Returns `{ ok, errors, assets }` where each
+ * error is `{ code, name, message }` and each accepted asset is
+ * `{ name, kind, mimeType, sizeBytes }`, sorted by name.
+ * Error codes: ASSET_NAME_INVALID, ASSET_TYPE_NOT_ALLOWED, ASSET_EMPTY,
+ * ASSET_CONTENT_MISMATCH, ASSET_NAME_DUPLICATE, ASSET_TOO_MANY.
+ */
+function validateBundledAssets(files) {
+  const list = Array.isArray(files) ? files : [];
+  const errors = [];
+  const assets = [];
+  const seenNames = new Set();
+  if (list.length > RULES.maxFiles) {
+    errors.push(
+      _error(
+        "ASSET_TOO_MANY",
+        null,
+        `a package can bundle at most ${RULES.maxFiles} files; this one has ${list.length}.`,
+      ),
+    );
+  }
+  for (const file of list) {
+    const error = _fileError(file || {}, seenNames);
+    if (error) {
+      errors.push(error);
+      continue;
+    }
+    const { kind, mimeType } = _sniff(file.bytes);
+    assets.push({ name: file.name, kind, mimeType, sizeBytes: file.bytes.length });
+  }
+  assets.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+  return { ok: errors.length === 0, errors, assets };
+}
+
+module.exports = {
+  BUNDLED_ASSET_DIRECTORY,
+  isValidBundledAssetName,
+  sniffBundledAssetType,
+  validateBundledAssets,
+};

package/dist/bundled-assets.js

@@ -0,0 +1,239 @@
+// The files a widget package ships in its assets/ directory: which names and
+// types are allowed. Pure and filesystem-free, so the CLI, the dev server, the
+// first-party packer and the backend all apply one rule set.
+// Keep bundled-assets.cjs in lockstep.
+
+import { CONTRACT } from "./contract.js";
+
+const RULES = CONTRACT.bundledAssets;
+const BUNDLED_ASSET_DIRECTORY = RULES.directory;
+const ALLOWED_EXTENSIONS = Object.values(RULES.types).flatMap(
+  (type) => type.extensions,
+);
+const NAME_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+
+const PNG = { kind: "image", mimeType: "image/png", extensions: ["png"] };
+const JPEG = { kind: "image", mimeType: "image/jpeg", extensions: ["jpg", "jpeg"] };
+const GIF = { kind: "image", mimeType: "image/gif", extensions: ["gif"] };
+const WEBP = { kind: "image", mimeType: "image/webp", extensions: ["webp"] };
+const WAV = { kind: "audio", mimeType: "audio/wav", extensions: ["wav"] };
+const MP3 = { kind: "audio", mimeType: "audio/mpeg", extensions: ["mp3"] };
+const M4A = { kind: "audio", mimeType: "audio/mp4", extensions: ["m4a"] };
+
+const PNG_SIGNATURE = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a];
+const JPEG_SIGNATURE = [0xff, 0xd8, 0xff];
+const M4A_BRANDS = ["M4A ", "M4B ", "mp42", "isom", "mp41"];
+
+function _hasBytes(bytes, signature, offset) {
+  if (bytes.length < offset + signature.length) return false;
+  return signature.every((byte, i) => bytes[offset + i] === byte);
+}
+
+function _hasText(bytes, text, offset) {
+  return _hasBytes(bytes, Array.from(text, (ch) => ch.charCodeAt(0)), offset);
+}
+
+// kbps by bitrate index; index 0 (free format) and 15 are never accepted.
+const MPEG_BITRATES = {
+  v1Layer1: [0, 32, 64, 96, 128, 160, 192, 224, 256, 288, 320, 352, 384, 416, 448],
+  v1Layer2: [0, 32, 48, 56, 64, 80, 96, 112, 128, 160, 192, 224, 256, 320, 384],
+  v1Layer3: [0, 32, 40, 48, 56, 64, 80, 96, 112, 128, 160, 192, 224, 256, 320],
+  v2Layer1: [0, 32, 48, 56, 64, 80, 96, 112, 128, 144, 160, 176, 192, 224, 256],
+  v2Layer2or3: [0, 8, 16, 24, 32, 40, 48, 56, 64, 80, 96, 112, 128, 144, 160],
+};
+// Hz by the header's version bits (3 = MPEG-1, 2 = MPEG-2, 0 = MPEG-2.5).
+const MPEG_SAMPLE_RATES = {
+  3: [44100, 48000, 32000],
+  2: [22050, 24000, 16000],
+  0: [11025, 12000, 8000],
+};
+const MPEG_LAYER_1 = 3;
+const MPEG_LAYER_3 = 1;
+
+function _mpegBitrateTable(isVersion1, layer) {
+  if (layer === MPEG_LAYER_1) return isVersion1 ? MPEG_BITRATES.v1Layer1 : MPEG_BITRATES.v2Layer1;
+  if (!isVersion1) return MPEG_BITRATES.v2Layer2or3;
+  return layer === MPEG_LAYER_3 ? MPEG_BITRATES.v1Layer3 : MPEG_BITRATES.v1Layer2;
+}
+
+/** Byte length of the MPEG audio frame whose header starts at `offset`, or 0. */
+function _mpegFrameLength(bytes, offset) {
+  if (bytes.length < offset + 4) return 0;
+  if (bytes[offset] !== 0xff || (bytes[offset + 1] & 0xe0) !== 0xe0) return 0;
+  const version = (bytes[offset + 1] >> 3) & 3;
+  const layer = (bytes[offset + 1] >> 1) & 3;
+  const bitrateIndex = bytes[offset + 2] >> 4;
+  const sampleRateIndex = (bytes[offset + 2] >> 2) & 3;
+  const padding = (bytes[offset + 2] >> 1) & 1;
+  if (version === 1 || layer === 0 || sampleRateIndex === 3) return 0;
+  if (bitrateIndex === 0 || bitrateIndex === 15) return 0;
+  const isVersion1 = version === 3;
+  const bitrate = _mpegBitrateTable(isVersion1, layer)[bitrateIndex] * 1000;
+  const sampleRate = MPEG_SAMPLE_RATES[version][sampleRateIndex];
+  if (layer === MPEG_LAYER_1) return (Math.floor((12 * bitrate) / sampleRate) + padding) * 4;
+  const samplesPerByte = layer === MPEG_LAYER_3 && !isVersion1 ? 72 : 144;
+  return Math.floor((samplesPerByte * bitrate) / sampleRate) + padding;
+}
+
+// A two-byte sync alone matches a UTF-16 BOM, so a second frame must follow.
+function _isMpegAudioAt(bytes, offset) {
+  const length = _mpegFrameLength(bytes, offset);
+  if (length === 0) return false;
+  const next = offset + length;
+  return next === bytes.length || _mpegFrameLength(bytes, next) > 0;
+}
+
+const ID3_HEADER_BYTES = 10;
+
+function _isMp3(bytes) {
+  if (!_hasText(bytes, "ID3", 0)) return _isMpegAudioAt(bytes, 0);
+  if (bytes.length < ID3_HEADER_BYTES || bytes[3] === 0xff || bytes[4] === 0xff) return false;
+  const size = [bytes[6], bytes[7], bytes[8], bytes[9]];
+  if (size.some((byte) => byte >= 0x80)) return false;
+  const tagBytes = (size[0] << 21) | (size[1] << 14) | (size[2] << 7) | size[3];
+  const footerBytes = bytes[5] & 0x10 ? ID3_HEADER_BYTES : 0;
+  return _isMpegAudioAt(bytes, ID3_HEADER_BYTES + tagBytes + footerBytes);
+}
+
+function _describe(type) {
+  return { kind: type.kind, mimeType: type.mimeType, extensions: [...type.extensions] };
+}
+
+function _sniff(bytes) {
+  if (_hasBytes(bytes, PNG_SIGNATURE, 0)) return PNG;
+  if (_hasBytes(bytes, JPEG_SIGNATURE, 0)) return JPEG;
+  if (_hasText(bytes, "GIF87a", 0) || _hasText(bytes, "GIF89a", 0)) return GIF;
+  if (_hasText(bytes, "RIFF", 0)) {
+    if (_hasText(bytes, "WEBP", 8)) return WEBP;
+    if (_hasText(bytes, "WAVE", 8)) return WAV;
+    return null;
+  }
+  if (_hasText(bytes, "ftyp", 4)) {
+    return M4A_BRANDS.some((brand) => _hasText(bytes, brand, 8)) ? M4A : null;
+  }
+  if (_isMp3(bytes)) return MP3;
+  return null;
+}
+
+/**
+ * Identify a bundled file from its leading bytes alone.
+ * Returns `{ kind: "image" | "audio", mimeType, extensions }`, or `null` when
+ * the bytes are not one of the bundled types.
+ */
+function sniffBundledAssetType(bytes) {
+  if (!bytes || typeof bytes.length !== "number") return null;
+  const type = _sniff(bytes);
+  return type ? _describe(type) : null;
+}
+
+function _extensionOf(name) {
+  const dot = name.lastIndexOf(".");
+  return dot === -1 ? "" : name.slice(dot + 1).toLowerCase();
+}
+
+function _isWellFormedName(name) {
+  return (
+    typeof name === "string" &&
+    name.length <= RULES.maxNameLength &&
+    NAME_RE.test(name) &&
+    !name.includes("..")
+  );
+}
+
+/** True when `name` may be used as a file name inside a package's assets/. */
+function isValidBundledAssetName(name) {
+  return _isWellFormedName(name) && ALLOWED_EXTENSIONS.includes(_extensionOf(name));
+}
+
+function _extensionList() {
+  const last = ALLOWED_EXTENSIONS[ALLOWED_EXTENSIONS.length - 1];
+  return `${ALLOWED_EXTENSIONS.slice(0, -1).join(", ")} and ${last}`;
+}
+
+function _error(code, name, rule) {
+  const where = `${BUNDLED_ASSET_DIRECTORY}/${name === null ? "" : name}`;
+  return { code, name, message: `${where}: ${rule}` };
+}
+
+function _fileError(file, seenNames) {
+  const { name, bytes } = file;
+  if (!_isWellFormedName(name)) {
+    return _error(
+      "ASSET_NAME_INVALID",
+      typeof name === "string" ? name : String(name),
+      "a bundled file name starts with a letter or digit, uses only letters, " +
+        `digits, dots, hyphens and underscores, and is at most ${RULES.maxNameLength} ` +
+        "characters long. Subdirectories are not allowed.",
+    );
+  }
+  const extension = _extensionOf(name);
+  if (!ALLOWED_EXTENSIONS.includes(extension)) {
+    return _error(
+      "ASSET_TYPE_NOT_ALLOWED",
+      name,
+      `only ${_extensionList()} files can be bundled.`,
+    );
+  }
+  if (seenNames.has(name.toLowerCase())) {
+    return _error(
+      "ASSET_NAME_DUPLICATE",
+      name,
+      "another bundled file has the same name when upper and lower case are ignored.",
+    );
+  }
+  seenNames.add(name.toLowerCase());
+  if (!bytes || !bytes.length) {
+    return _error("ASSET_EMPTY", name, "the file is empty.");
+  }
+  const sniffed = _sniff(bytes);
+  if (!sniffed || !sniffed.extensions.includes(extension)) {
+    return _error(
+      "ASSET_CONTENT_MISMATCH",
+      name,
+      `the file's content is not a valid .${extension} file.`,
+    );
+  }
+  return null;
+}
+
+/**
+ * Validate the files of a package's assets/ directory.
+ * `files` is `[{ name, bytes }]`. Returns `{ ok, errors, assets }` where each
+ * error is `{ code, name, message }` and each accepted asset is
+ * `{ name, kind, mimeType, sizeBytes }`, sorted by name.
+ * Error codes: ASSET_NAME_INVALID, ASSET_TYPE_NOT_ALLOWED, ASSET_EMPTY,
+ * ASSET_CONTENT_MISMATCH, ASSET_NAME_DUPLICATE, ASSET_TOO_MANY.
+ */
+function validateBundledAssets(files) {
+  const list = Array.isArray(files) ? files : [];
+  const errors = [];
+  const assets = [];
+  const seenNames = new Set();
+  if (list.length > RULES.maxFiles) {
+    errors.push(
+      _error(
+        "ASSET_TOO_MANY",
+        null,
+        `a package can bundle at most ${RULES.maxFiles} files; this one has ${list.length}.`,
+      ),
+    );
+  }
+  for (const file of list) {
+    const error = _fileError(file || {}, seenNames);
+    if (error) {
+      errors.push(error);
+      continue;
+    }
+    const { kind, mimeType } = _sniff(file.bytes);
+    assets.push({ name: file.name, kind, mimeType, sizeBytes: file.bytes.length });
+  }
+  assets.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+  return { ok: errors.length === 0, errors, assets };
+}
+
+export {
+  BUNDLED_ASSET_DIRECTORY,
+  isValidBundledAssetName,
+  sniffBundledAssetType,
+  validateBundledAssets,
+};