@colixsystems/widget-sdk 0.197.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.
@@ -23,6 +24,8 @@ The data layer lives in **four separate domain-client packages**, each instantia
 | **CORE** | `useUser()` | `{ id, email, displayName, photoUrl, roles, groupIds }` | `ctx.user` (host-built context, **camelCase** — not a wire payload; `id` null when anonymous) — no scope. `photoUrl` is the user's own profile photo as an absolute URL, or `null`. |
 | **CORE** | `useUserPhoto()` | `{ url, canEdit, upload, remove, uploading, error }` | `ctx.user` + the optional `ctx.account` — no scope. Changes the signed-in user's OWN profile photo. `canEdit` is false when nobody is signed in or the host cannot change it; `upload` / `remove` then reject. |
 | **CORE** | `useNavigation()` | `{ goTo, goBack, push, replace, back, currentRoute, openLink }` | `ctx.navigation` — no scope. `goTo(pageIdOrSlug, params?)` accepts a page UUID (a `pageRef` prop) **or its slug** (a row's page-key field) — both hosts resolve either (`openLink` for a link of unknown shape; a known external URL can also use the `Linking` primitive) |
+| **CORE** | `useFilePreview(file)` | `{ uri }` | No scope. A temporary address an `<Image>` can show for a file the person picked but has not uploaded yet (a photo in a composer). Native picks use their own uri; on the web the SDK creates and releases an object URL, which widgets may not do themselves. `uri` is null for no file. |
+| **CORE** | `usePageBadge(count)` | `{ supported }` | `ctx.navigation.setBadge` — no scope. Puts `count` on the menu entry or tab of the page the widget is on (a chat's unread messages). The host sums the page's widgets and keeps the last count after the widget leaves the screen, until it reports again; `0` clears this widget's share. `supported` is false where the host draws no page badges (the Builder canvas). |
 | **CORE** | `useRouteParams()` | `{ [paramKey]: value }` | `ctx.navigation.currentRoute.params` — no scope. The nav params the previous page passed via `goTo(pageId, params)`; the flat accessor for master→detail (read `recordId` on a detail page). Empty object when none. |
 | **CORE** | `usePageContext()` | `{ params, records }` | `ctx.pageContext` — no scope. The page's DECLARED parameters, resolved once by the host: `params` are coerced to their declared types, `records` holds the row already fetched for each `record` param (read it instead of fetching again). Both empty when the page declares none. |
 | **CORE** | `useWidgetRoute(initial)` | `[state, setState]` | `ctx.widgetRoute` — no scope. Where YOUR WIDGET is, persisted by the host so it survives a reload and travels in a shared link (the `w_<instanceId>` query key on web, the screen's route params natively): the folder a browser has opened, a wizard step, a selected tab, a list's sort and search. `useState` semantics over an object — writes MERGE, `null` clears a key back to its `initial`, and `initial` is read once. Values are scalars or flat arrays of scalars, size- and length-capped; anything else is not stored. NOT history (Back still leaves the page, on both platforms). Degrades to component state on the Studio canvas. |
@@ -57,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:*`) |
@@ -67,6 +71,8 @@ The data layer lives in **four separate domain-client packages**, each instantia
 | **FILESTORE** (`ctx.filestore`) | `usePdfExport({ spaceType, folderId })` (optional: spaceType, folderId) | `{ openPdf, opening, canOpenPdf, exportToPdf, exporting, error, lastExported }` | `ctx.filestore.files.renderPdf` + `ctx.device.pdfViewer`, `ctx.filestore.files.exportPdf` — `files.write:*`. `openPdf(html, { fileName? })` renders the HTML to a PDF server-side and OPENS it (web: PDF tab; native: print / share sheet) without saving. `exportToPdf(html, { fileName?, folderId? })` renders it and saves it as a file (`application/pdf`). Same server-side renderer on web + native. |
 | **PAYMENTS** (`ctx.payments`) | `usePayments()` | `{ requestPayment, getPayment }` | `ctx.payments.*` — `payments.charge:appUser`. Rejects with `PaymentError { code, message, retryable }`; when `retryable` is `false` show `message` and drop the retry. Charges are accepted ONLY in the currency the workspace sells in — omit `currency` and the platform applies it (a disagreeing literal is a publish-blocking `payment-currency` finding). |
 | **NOTIFICATIONS** (`ctx.notifications`) | `useSendNotification()` | `{ send, sending, error }` | `ctx.notifications.send` — `notifications.send:appUser`. `send({ recipient_user_id, title, body, link?, payload? })` notifies one app user in the same workspace; call from an event handler (never render); rejects with `NotificationError`. |
+| **NOTIFICATIONS** (`ctx.notifications`) | `useRecordMutes(tableId)` | `{ isMuted, loading, error, refetch }` | `ctx.notifications.mutes` — no scope. Which records of one table the signed-in user has muted, in one request for a whole list; `isMuted(recordId)` turns false when a timed mute lapses, and a `useRecordMute` write shows at once. |
+| **NOTIFICATIONS** (`ctx.notifications`) | `useRecordMute(tableId, recordId)` | `{ muted, mutedUntil, loading, error, mute, unmute, refetch }` | `ctx.notifications.mutes` — no scope. Mutes one record's notifications for the signed-in user, `mute(until)` with an ISO time, a `Date`, or `null` for until unmuted. Needs read access to the record (`RECORD_NOT_FOUND` otherwise). |
 | **IDENTIFICATION** (`ctx.identification`) | `useIdentification({ provider, purpose, pollIntervalMs })` (optional: every key, and the whole argument) | `{ available, status, qr, autoStartToken, message, identity, identificationId, start, refresh, cancel, reset, … }` | `ctx.identification.*` — no scope (the visitor is deliberately NOT signed in). Gate the UI on `available`; `start()` opens the order and the hook polls to completion. `identity` carries `personal_number_masked` + a stable `subject_hash` — never a raw personal number. |
 
 All list calls return the `{ data, meta }` envelope; the read hooks unwrap `res.data` for you. There is no `useWorkspace()` or `useLogger()` hook — read the theme via `useTheme()` and the locale via `useI18n()`; the host logger lives on `ctx.logger` (`{ debug, info, warn, error }`).
@@ -77,7 +83,80 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.197.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.
+
+**`useDirectory({ ids })` resolves names for the people a widget already knows about.** Pass up to 100 user ids — message senders, members of a conversation — and get their `{ id, name, role }` rows without loading the whole roster; pair it with `q` for a server-side people search. Additive.
+
+**Files can be attached to a datastore record and stay private to it.** `useFilestoreUpload({ spaceType: "record", recordId })` attaches the uploaded file to that record, and `useFilestoreFiles({ spaceType: "record", recordId, type })` lists its attachments newest first (`type: "media"` for images and videos, `"document"` for the rest). Exactly the people who may read the record may read its attachments, through the same permission check as the record itself. Uploading needs write on the record, only the uploader may delete an attachment, and removing the record removes its attachments. A record attachment's URL is issued to one viewer and lives about ten minutes, so re-resolve it (`useFilestoreFile(id).refetch()`) when an image fails to load. The new `useFilestoreDelete()` returns `{ remove, removing, error }`: `remove(fileId)` deletes a record attachment permanently (only its uploader may) and moves any other file to the trash. `useFilestoreCopy().copy(fileId, { spaceType: "record", recordId })` attaches a copy of a file to a record, with the same write check as uploading there. `useCamera().pick({ multiple: true })` lets the user choose up to 10 photos from the device library at once and resolves an array of assets; `pick()` alone is unchanged. `<Avatar seed={user.id} />` draws the initials on that person's own colour, the same one the Studio's member lists use, and `avatarColorFor(seed)` returns it.
+
+**A `datastoreTemplate` can make inherited access read-only and stamp author columns on the server.** An `inheritAcl` RELATION column may add `inheritAclReadOnly: true`. Rows then inherit only READ access from the row they point at: members of a conversation read every message in it and may post into it, but change or delete only the messages they created (pair it with `grantCreatorPermissions`). This also holds down a chain, such as a reaction on a message in a conversation. A column may declare `defaultValue`, which is written when a create omits the column. Use `"@currentUser"` on a USER column, `"@now"` on a DATE or DATETIME column, or a literal of the column's own type. FILE, RELATION and USER_GROUP columns take no default, because ids belong to the installing workspace. `defaultLocked: true` on a `"@currentUser"` or `"@now"` default makes the server always stamp it. Any value a client sends for the column is ignored on create and on update, so a `Sender` or `CreatedBy` column is always the real author. `immutable: true` makes a column write-once: a create sets it from the value sent or the default, and any value sent for it on update is ignored, so a message's `Conversation` cannot be moved after it is posted. It is not valid on a MANY_TO_MANY relation, whose links live outside the row. Additive.
+
+**A user can mute one record's notifications.** `useRecordMute(tableId, recordId)` returns `{ muted, mutedUntil, loading, error, mute, unmute, refetch }`. `mute(until)` takes an ISO time or a `Date`, or `null` (or nothing) to mute until `unmute()`. While a mute is active, a server action's `notifications.notifyRecordSubjects` on that record sends the user nothing: no inbox row, no push, no email. `mutedUntil` is the ISO time the mute ends, or `null` when it lasts until unmuted, and `muted` turns false by itself when that time passes. The user must be able to read the record, so a record they cannot read fails with `NotificationError { code: "RECORD_NOT_FOUND" }`, just like one that does not exist. A falsy id returns a stable not-muted result with no request. On a host without `ctx.notifications.mutes` (the Builder canvas preview) the hook reads not muted, and `mute()` / `unmute()` reject with `NOTIFICATIONS_UNAVAILABLE`. No scope is needed, because it only changes the user's own setting. To show mutes in a list, call `useRecordMutes(tableId)` once: `isMuted(recordId)` answers for every row from one request, and a mute made through `useRecordMute` on the same table shows at once. `NotificationError.code` now carries the server's code when it sends one (`INVALID_TITLE`, `RECORD_NOT_FOUND`, …), and a 401 reads `AUTH_REQUIRED`. Additive.
+
+```jsx
+import { useRecordMute, Pressable, Text } from "@colixsystems/widget-sdk";
+
+function MuteToggle({ tableId, conversationId }) {
+  const { muted, mute, unmute } = useRecordMute(tableId, conversationId);
+  return (
+    <Pressable onPress={() => (muted ? unmute() : mute(null)).catch(() => {})}>
+      <Text>{muted ? "Unmute" : "Mute"}</Text>
+    </Pressable>
+  );
+}
+```
+
+**A list can show every muted record at once.** `useRecordMutes(tableId)` returns `{ isMuted, loading, error, refetch }` from one request, so a conversation list marks its muted rows without a read per row. No scope. Additive.
+
+**A widget can put a count on its page's menu entry.** `usePageBadge(count)` returns `{ supported }` and shows `count` on the menu entry or tab of the page the widget is on, on the web Player and in the exported app, through the new optional `ctx.navigation.setBadge`. The host adds up the counts of the page's widgets and keeps the last one after the widget leaves the screen; `0` clears it. No scope. Additive.
+
+**A picked file can be shown before it is uploaded.** `useFilePreview(file)` returns `{ uri }` for an `<Image>`: a native pick's own `uri`, or an object URL the hook releases on the web. No scope. Additive.
+
+**Videos play inline on both hosts.** `<Video source={url} />` plays a file with the platform's own controls and shows its first frame before playback: the browser's `<video>` on the web, expo-video's VideoView in the exported app. `contentFit` is `"contain"` (default) or `"cover"`, `controls` defaults to `true`, `autoPlay` starts it muted, and `onError()` fires when this host cannot play the file, so offer a download instead. A browser plays only the codecs it supports; H.264 MP4 plays everywhere.
+
+```jsx
+import { Video } from "@colixsystems/widget-sdk";
+
+<Video
+  source={file.url}
+  contentFit="cover"
+  style={{ width: 240, height: 180, borderRadius: theme.radii.md, overflow: "hidden" }}
+  onError={() => setPlayable(false)}
+/>
+```
+
+**A widget with pages of its own can answer Android's back button.** `useHardwareBack(handler)` runs `handler` on a back press while the widget's screen is in view; return `true` when it went back a step (closed a thread, left a settings page), `false` to let the app go back, and pass `null` while there is nothing to go back from. The exported app answers only for the screen in view, so a widget kept mounted on another tab never swallows the press. `supported` is `false` on the web Player, where browsers have no hardware back, so keep a visible back control too. No scope. Additive.
+
+**The photo picker chooses several, and videos.** `useCamera().pick({ multiple: true })` resolves an array of up to 10 assets, and `pick({ videos: true })` offers videos beside photos. A video asset has a `video/*` `mimeType` and `durationMs` (`null` for a photo); on iOS it arrives as H.264 so other devices can play it. Additive.
+
+**A person keeps one avatar everywhere.** `<Avatar seed={userId}>` and `avatarColorFor(seed)` give a person the monogram colour the Studio's member lists use, and `initialsFor` now gives a one-word name two letters ("Börje" → "BÖ"), so an `<Avatar>` of a single-name user changes from one letter to two.
+
+**Fixes.** `<Overlay>` opens at once under React StrictMode on the web: react-native-web's `Modal` lost its page container to StrictMode's effect replay, so a sheet stayed invisible until an unrelated re-render; the web binding now uses its own modal layer with the same dialog role, Escape, focus trap and focus return. `useDatastoreMutation` returns one stable object while its methods are unchanged, so a widget can list it as a dependency. `NotificationError.code` carries the server's code when it sends one.
 
 ### What's new in 0.197.0 (contract 1.157.0)
 
@@ -2540,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
@@ -2589,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/avatar-color.js

@@ -0,0 +1,35 @@
+// sc-10268 — the ONE person tint, shared by the Studio's member lists and the
+// SDK `<Avatar seed>`, so a person seeded the same way is one colour everywhere.
+
+// Brand-neutral accents, each dark enough for white initials.
+const AVATAR_COLORS = Object.freeze([
+  "#0f766e",
+  "#3f5bd6",
+  "#b0562a",
+  "#7a4bcc",
+  "#b83b5e",
+  "#2f7d4f",
+  "#9333ea",
+  "#0369a1",
+  "#c2410c",
+  "#0e7490",
+]);
+
+/**
+ * A stable colour for a seed (a user id, an email), or null for no seed.
+ *
+ * FNV-1a plus a murmur-style avalanche: a plain `hash * 31 % N` keys the bucket
+ * off the low bits, which barely mix, so most seeds collide on one colour.
+ */
+export function avatarColorFor(seed) {
+  if (typeof seed !== "string" || !seed) return null;
+  let h = 2166136261;
+  for (let i = 0; i < seed.length; i += 1) {
+    h ^= seed.charCodeAt(i);
+    h = Math.imul(h, 16777619);
+  }
+  h ^= h >>> 13;
+  h = Math.imul(h, 0x5bd1e995);
+  h ^= h >>> 15;
+  return AVATAR_COLORS[(h >>> 0) % AVATAR_COLORS.length];
+}

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,
+};