@colixsystems/widget-sdk 0.100.0 → 0.101.0

package/README.md

@@ -99,6 +99,28 @@ Host-integration surface only: no author-facing hook, prop, primitive, or manife
 
 Host-integration surface only: no author-facing hook, prop, primitive, or manifest field changed. `CONTRACT.version` → `1.66.0`.
 
+### What's new in 0.101.0 (contract 1.75.0)
+
+**Render an image at the size you actually show it — `file.urls` (sc-5699).** Every Filestore file record now carries a delivery **size ladder** beside `url`:
+
+```js
+const { files } = useFilestoreFiles({ spaceType: 'public' });
+// a 128px grid downloads 128px images, not the 4096px originals
+files.map((f) => <Image key={f.id} source={{ uri: f.urls.thumbnail }} />);
+
+const { url, urls } = useFilestoreFile(fileId);
+<Image source={{ uri: urls?.large }} />;   // a detail view
+<a href={url}>Download original</a>;       // the full-size bytes
+```
+
+The rungs are `thumbnail` (128px), `card` (512px), `large` (1024px), and `hero` (2048px), each a **longest-edge** target. Pick the next rung **up** from the size you render at, so a 2x/3x screen still has enough pixels — a 100px avatar wants `thumbnail`, a 400px card wants `card`.
+
+`urls` is **always fully populated**, so it never needs a fallback branch: a type with no ladder — SVG, an animated GIF, a PDF, a video — points every rung at the original. A rung is also never *upscaled*: ask for `hero` on a 300px image and you get the 300px original rather than a blurry 2048px copy.
+
+`useFilestoreFile` returns `urls` alongside `url`, and — like `url` — it is `null` until the fetch resolves, so read the top-level value rather than `file.urls`.
+
+Requires `@colixsystems/filestore-client` ≥ 0.8.0. `CONTRACT.version` → `1.75.0`. Additive — `url` and `presigned_url` are unchanged, so a widget that ignores `urls` behaves exactly as before.
+
 ### What's new in 0.100.0 (contract 1.74.0)
 
 **Opt out of image compression on upload — `useFilestoreUpload({ compress })` (sc-5402).** A file uploaded through `POST /api/v1/filestore/files` now has its raster images compressed to WebP again (EXIF-stripped, longest edge capped at 4096 px), which is the right default for anything the app renders. When the ORIGINAL bytes matter — a document archive, a photo the user re-downloads, anything with an exact-bytes requirement — pass `compress: false`, either on the hook or per call:
@@ -651,8 +673,8 @@ Also: `useFileSignatures(fileIds)` is now **self-scoped** (the caller's own sign
 ### What's new in 0.30.0
 
 **Filestore browsing + BankID file signing for widgets (REQ-FS / REQ-SIGN).** Three new hooks read a newly-injected `ctx.filestore` (the `@colixsystems/filestore-client`, now constructed by both the web and native hosts):
-- `useFilestoreFiles({ spaceType, folderId?, q?, type? })` → `{ files, loading, error, refetch }` — browses the end-user's Filestore space. The hook resolves `owner_id` from the host context (tenant for a project space, the app user for a personal space), so the widget only picks the space. Every row carries a ready-to-render `url` (its absolutized `presigned_url`), so a gallery renders `files.map(f => f.url)` directly — no per-row `useFilestoreFile` call.
-- `useFilestoreFile(fileId)` → `{ file, url, loading, error, refetch }` — resolves ONE file id to a displayable `url` (its `presigned_url`, absolutized for web + native) via `ctx.filestore.files.get(id)`. **Read the top-level `url`** — the returned `file` is `null` until the fetch resolves (and for an empty id), so `file.url` throws on the first render; it is correct only after a null check. **Never compose a file URL yourself** — the bytes are served only from a server-signed token URL, so a hand-built path like `/api/files/<id>` can never resolve (the linter's `no-host-api-url` rule flags it, including the `${location.origin}/api/files/…` form). A datastore `FILE` column holds — and reads back as — that **bare file-id string**; it is NOT hydrated into an object the way a `RELATION` (`{ id, label }`) or `USER` (`{ id, name }`) column is, so pass the value straight to the hook (no `{ id }` / `{ url }` unwrapping guard). Empty / deleted / not-found ids resolve to `url: null` so a display widget shows a fallback. When you render `url` in an `<Image>` that fills its container, size it with `aspectRatio` (e.g. `{ width: "100%", aspectRatio: 1 }`) or pixels — never a percentage `height`, which React Native collapses to 0 against a content-sized parent, so the image loads but is invisible. Requires `files.read:*`.
+- `useFilestoreFiles({ spaceType, folderId?, q?, type? })` → `{ files, loading, error, refetch }` — browses the end-user's Filestore space. The hook resolves `owner_id` from the host context (tenant for a project space, the app user for a personal space), so the widget only picks the space. Every row carries a ready-to-render `url` (its absolutized `presigned_url`), so a gallery renders `files.map(f => f.url)` directly — no per-row `useFilestoreFile` call. Every row ALSO carries `urls` — the size ladder `{ thumbnail, card, large, hero }` at 128 / 512 / 1024 / 2048px longest edge — so a thumbnail grid should render `f.urls.thumbnail` rather than pulling the full-size original for every tile.
+- `useFilestoreFile(fileId)` → `{ file, url, urls, loading, error, refetch }` — resolves ONE file id to a displayable `url` (its `presigned_url`, absolutized for web + native) via `ctx.filestore.files.get(id)`. **Read the top-level `url`** — the returned `file` is `null` until the fetch resolves (and for an empty id), so `file.url` throws on the first render; it is correct only after a null check. **Never compose a file URL yourself** — the bytes are served only from a server-signed token URL, so a hand-built path like `/api/files/<id>` can never resolve (the linter's `no-host-api-url` rule flags it, including the `${location.origin}/api/files/…` form). A datastore `FILE` column holds — and reads back as — that **bare file-id string**; it is NOT hydrated into an object the way a `RELATION` (`{ id, label }`) or `USER` (`{ id, name }`) column is, so pass the value straight to the hook (no `{ id }` / `{ url }` unwrapping guard). Empty / deleted / not-found ids resolve to `url: null` so a display widget shows a fallback. When you render `url` in an `<Image>` that fills its container, size it with `aspectRatio` (e.g. `{ width: "100%", aspectRatio: 1 }`) or pixels — never a percentage `height`, which React Native collapses to 0 against a content-sized parent, so the image loads but is invisible. Requires `files.read:*`.
 - `useFilestoreFolders({ spaceType, parentFolderId?, q?, enabled? })` → `{ folders, loading, error, refetch }` — the folder-navigation companion to `useFilestoreFiles`; pass `enabled:false` to suspend fetching.
 - `useFilestoreUpload({ spaceType, folderId?, compress? })` → `{ upload, uploading, error, lastUploaded }` — POSTs a multipart upload to `ctx.filestore.files.upload`. Resolves `owner_id` from the host context (like the read hooks) so the widget only picks the space + destination folder. Uploaded images are compressed to WebP by the backend; pass `compress: false` (on the hook, or per `upload(file, { compress })`) to store the file byte-for-byte — use it whenever the original matters. Pair with the `<FilePicker>` primitive for the visible trigger. Requires the `files.write:*` scope.
 - `useFileSignature(fileId)` → `{ status, qr, signerName, verdict, initiate, refresh, cancel, verify, … }` — drives a BankID signing flow for a file (the backend hashes the bytes server-side, binds the digest into the signature, and verifies the proof offline).

package/dist/contract.cjs

@@ -746,7 +746,15 @@ const HOOKS = [
       "logged-out Player visitors. Reads ctx.filestore.files.list and unwraps " +
       "{ data, meta } to the files array. Every row carries a ready-to-render " +
       "`url` (its absolutized presigned_url, aliased by the filestore client) " +
-      "so a gallery renders `files.map(f => f.url)` directly.",
+      "so a gallery renders `files.map(f => f.url)` directly. Every row ALSO " +
+      "carries `urls` — the delivery size ladder `{ thumbnail, card, large, " +
+      "hero }` at 128 / 512 / 1024 / 2048px longest edge. PREFER a rung over " +
+      "`url` whenever the image is rendered smaller than full size: a grid of " +
+      "thumbnails should read `f.urls.thumbnail`, a card list `f.urls.card`. " +
+      "Pick the next rung UP from the rendered size so a 2x/3x screen still " +
+      "has enough pixels. `urls` is always fully populated — a type with no " +
+      "ladder (SVG, GIF, a PDF) points every rung at the original — so it " +
+      "never needs a fallback branch.",
     returnShape: {
       files: "FilestoreFile[]",
       loading: "boolean",
@@ -773,10 +781,14 @@ const HOOKS = [
       "stays null for an empty id), so `file.url` throws on the first render. " +
       "Every file record the client returns does carry the same `url` alias, " +
       "so `file.url` is correct once you have null-checked `file`. " +
+      "`file.urls` carries the size ladder `{ thumbnail, card, large, hero }` " +
+      "(128 / 512 / 1024 / 2048px longest edge) — reach for a rung whenever " +
+      "the image renders smaller than full size, picking the next rung UP. " +
       "NEVER build a file URL by hand from an id — no route serves one.",
     returnShape: {
       file: "FilestoreFile | null",
       url: "string | null",
+      urls: "{ thumbnail, card, large, hero } | null",
       loading: "boolean",
       error: "Error | null",
       refetch: "() => Promise<void>",
@@ -3209,7 +3221,7 @@ const CONTRACT = deepFreeze({
   //    are compressed to WebP by default; `compress: false` stores the file
   //    byte-for-byte. Existing callers are unaffected — the field is only sent
   //    when the opt-out is chosen.
-  version: "1.74.0",
+  version: "1.75.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -746,7 +746,15 @@ const HOOKS = [
       "logged-out Player visitors. Reads ctx.filestore.files.list and unwraps " +
       "{ data, meta } to the files array. Every row carries a ready-to-render " +
       "`url` (its absolutized presigned_url, aliased by the filestore client) " +
-      "so a gallery renders `files.map(f => f.url)` directly.",
+      "so a gallery renders `files.map(f => f.url)` directly. Every row ALSO " +
+      "carries `urls` — the delivery size ladder `{ thumbnail, card, large, " +
+      "hero }` at 128 / 512 / 1024 / 2048px longest edge. PREFER a rung over " +
+      "`url` whenever the image is rendered smaller than full size: a grid of " +
+      "thumbnails should read `f.urls.thumbnail`, a card list `f.urls.card`. " +
+      "Pick the next rung UP from the rendered size so a 2x/3x screen still " +
+      "has enough pixels. `urls` is always fully populated — a type with no " +
+      "ladder (SVG, GIF, a PDF) points every rung at the original — so it " +
+      "never needs a fallback branch.",
     returnShape: {
       files: "FilestoreFile[]",
       loading: "boolean",
@@ -773,10 +781,14 @@ const HOOKS = [
       "stays null for an empty id), so `file.url` throws on the first render. " +
       "Every file record the client returns does carry the same `url` alias, " +
       "so `file.url` is correct once you have null-checked `file`. " +
+      "`file.urls` carries the size ladder `{ thumbnail, card, large, hero }` " +
+      "(128 / 512 / 1024 / 2048px longest edge) — reach for a rung whenever " +
+      "the image renders smaller than full size, picking the next rung UP. " +
       "NEVER build a file URL by hand from an id — no route serves one.",
     returnShape: {
       file: "FilestoreFile | null",
       url: "string | null",
+      urls: "{ thumbnail, card, large, hero } | null",
       loading: "boolean",
       error: "Error | null",
       refetch: "() => Promise<void>",
@@ -3209,7 +3221,7 @@ const CONTRACT = deepFreeze({
   //    are compressed to WebP by default; `compress: false` stores the file
   //    byte-for-byte. Existing callers are unaffected — the field is only sent
   //    when the opt-out is chosen.
-  version: "1.74.0",
+  version: "1.75.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/hooks.js

@@ -2768,7 +2768,11 @@ export function useFilestoreFile(fileId) {
 
   const url =
     file && typeof file.presigned_url === "string" ? file.presigned_url : null;
-  return { file, url, loading, error, refetch };
+  // REQ-FS-15: the size ladder, surfaced beside `url` for the same reason —
+  // `file` is null until the fetch resolves, so `file.urls` throws on first
+  // render. Null until then, exactly like `url`.
+  const urls = file && file.urls && typeof file.urls === "object" ? file.urls : null;
+  return { file, url, urls, loading, error, refetch };
 }
 
 /**

package/dist/linter.cjs

@@ -392,6 +392,33 @@ function _hostApiUrlRules(source) {
   return findings;
 }
 
+// sc-5619 — see linter.js for the rationale comment. The two files must stay
+// in lockstep (the contract test asserts behaviour-equivalence).
+const PAGE_URL_RE = /["'`][^"'`]*\/play\/|\/play\/\$\{/;
+
+function _handBuiltPageUrlRules(source) {
+  const findings = [];
+  const lines = _stripNonCode(source, { keepStrings: true }).split(/\r?\n/);
+  for (let i = 0; i < lines.length; i += 1) {
+    if (!PAGE_URL_RE.test(lines[i])) continue;
+    findings.push({
+      rule: "no-hand-built-page-url",
+      severity: "error",
+      label:
+        `source builds a "/play/…" app URL by hand — the URL shape belongs ` +
+        `to the host, not the widget, so a hardcoded one breaks on a ` +
+        `workspace's own domain (where a page is "/page/<slug>", with no ` +
+        `workspace id) and leaks the workspace id into the address bar. ` +
+        `Navigate with useNavigation().goTo(pageId) — the page id comes from ` +
+        `a pageRef prop — and follow a link you did not build with ` +
+        `useNavigation().openLink(link).`,
+      line: i + 1,
+      snippet: lines[i].trim().slice(0, 200),
+    });
+  }
+  return findings;
+}
+
 // sc-4085 — see linter.js for the rationale comment. The two files must stay
 // in lockstep (the contract test asserts behaviour-equivalence).
 function _translationApiRules(source) {
@@ -1166,6 +1193,7 @@ function lintSource(source, options) {
   );
   findings.push(..._hostApiUrlRules(source));
   findings.push(..._translationApiRules(source));
+  findings.push(..._handBuiltPageUrlRules(source));
   findings.push(..._lucideIconRules(source));
   findings.push(..._reactInScopeRules(source));
   findings.push(..._imagePercentHeightRules(source));

package/dist/linter.js

@@ -437,6 +437,49 @@ function _hostApiUrlRules(source) {
   return findings;
 }
 
+// sc-5619 — no-hand-built-page-url.
+//
+// A published app answers on two URL shapes: `/play/<tenantId>/page/<slug>` on
+// the platform host, and `/page/<slug>` at the workspace's own domain. The host
+// owns that choice (`playerPath.js` on web, react-navigation natively), so a
+// widget that builds the path itself — almost always from the `workspace.id` the
+// SDK hands it — hardcodes ONE shape and breaks on the other: on a custom domain
+// it rewrites the customer's clean domain back to the platform form and
+// republishes their workspace id in the address bar.
+//
+// An `error` with no opt-out directive, like `no-external-translation-api`: the
+// SDK covers every legitimate case, so there is no correct code to rescue.
+// Navigate with `useNavigation().goTo(pageId)`, and follow a link whose shape
+// the widget does NOT control (a datastore value, a notification link) with
+// `useNavigation().openLink(link)` — that routes through the shared resolver,
+// which already accepts either shape and rebuilds the one this host uses.
+const PAGE_URL_RE = /["'`][^"'`]*\/play\/|\/play\/\$\{/;
+
+function _handBuiltPageUrlRules(source) {
+  const findings = [];
+  // Strings kept, comments blanked: the literal lives IN a string, but a comment
+  // or doc line quoting `/play/<id>` must not block a publish.
+  const lines = _stripNonCode(source, { keepStrings: true }).split(/\r?\n/);
+  for (let i = 0; i < lines.length; i += 1) {
+    if (!PAGE_URL_RE.test(lines[i])) continue;
+    findings.push({
+      rule: "no-hand-built-page-url",
+      severity: "error",
+      label:
+        `source builds a "/play/…" app URL by hand — the URL shape belongs ` +
+        `to the host, not the widget, so a hardcoded one breaks on a ` +
+        `workspace's own domain (where a page is "/page/<slug>", with no ` +
+        `workspace id) and leaks the workspace id into the address bar. ` +
+        `Navigate with useNavigation().goTo(pageId) — the page id comes from ` +
+        `a pageRef prop — and follow a link you did not build with ` +
+        `useNavigation().openLink(link).`,
+      line: i + 1,
+      snippet: lines[i].trim().slice(0, 200),
+    });
+  }
+  return findings;
+}
+
 // sc-4085 — no-external-translation-api.
 //
 // Translation is a platform capability, not a third-party API: `useTranslate()`
@@ -1327,6 +1370,7 @@ export function lintSource(source, options) {
   // REQ-WSDK-PLATFORM §3.5: soft host-API URL warning (does not block).
   findings.push(..._hostApiUrlRules(source));
   findings.push(..._translationApiRules(source));
+  findings.push(..._handBuiltPageUrlRules(source));
   findings.push(..._lucideIconRules(source));
   // sc-2353 — widget source must be self-contained (reference React ⇒ import it).
   findings.push(..._reactInScopeRules(source));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.100.0",
+  "version": "0.101.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "type": "module",
   "main": "./dist/index.js",
@@ -48,7 +48,7 @@
   ],
   "scripts": {
     "build": "node scripts/build.js",
-    "test": "node --test src/__tests__/contract.test.js src/__tests__/hooks-users.test.js src/__tests__/hooks-groups.test.js src/__tests__/hooks-invites.test.js src/__tests__/hooks-schema.test.js src/__tests__/hooks-assets-by-tag.test.js src/__tests__/hooks-filestore-upload.test.js src/__tests__/hooks-filestore-file.test.js src/__tests__/hooks-mutation.test.js src/__tests__/hooks-payments.test.js src/__tests__/hooks-record-permissions.test.js src/__tests__/hooks-geolocation.test.js src/__tests__/hooks-section-empty.test.js src/__tests__/hooks-widget-event.test.js src/__tests__/hooks-widget-input.test.js src/__tests__/hooks-identification.test.js src/__tests__/hooks-subscription.test.js src/__tests__/hooks-volatile-query-key.test.js src/__tests__/linter-users-scope.test.js src/__tests__/linter-comments.test.js src/__tests__/linter-translation-api.test.js src/__tests__/linter-image-height.test.js src/__tests__/linter-measured-padding.test.js src/__tests__/linter-payment-error.test.js src/__tests__/linter-platform.test.js src/__tests__/linter-react-import.test.js src/__tests__/lucide-icon-names.test.js src/__tests__/lucideIconName.test.js src/__tests__/manifest-actions.test.js src/__tests__/widget-translations.test.js src/__tests__/hooks-translate.test.js src/__tests__/devserver.test.js src/__tests__/host-externals.test.js src/__tests__/datetimepicker.test.js src/__tests__/property-schema-resolve.test.js src/__tests__/theme-components-parity.test.js src/__tests__/navigation-parity.test.js src/__tests__/theme-depth-tokens.test.js src/__tests__/toast-host.test.js src/__tests__/hooks-domain-error-mapping.test.js src/__tests__/linter-datastore-error.test.js src/__tests__/linter-write-gating.test.js src/__tests__/hooks-speech-to-text.test.js src/__tests__/hooks-bound-columns.test.js src/__tests__/hooks-stable-query.test.js src/__tests__/hooks-can-write.test.js"
+    "test": "node --test src/__tests__/contract.test.js src/__tests__/hooks-users.test.js src/__tests__/hooks-groups.test.js src/__tests__/hooks-invites.test.js src/__tests__/hooks-schema.test.js src/__tests__/hooks-assets-by-tag.test.js src/__tests__/hooks-filestore-upload.test.js src/__tests__/hooks-filestore-file.test.js src/__tests__/hooks-mutation.test.js src/__tests__/hooks-payments.test.js src/__tests__/hooks-record-permissions.test.js src/__tests__/hooks-geolocation.test.js src/__tests__/hooks-section-empty.test.js src/__tests__/hooks-widget-event.test.js src/__tests__/hooks-widget-input.test.js src/__tests__/hooks-identification.test.js src/__tests__/hooks-subscription.test.js src/__tests__/hooks-volatile-query-key.test.js src/__tests__/linter-users-scope.test.js src/__tests__/linter-comments.test.js src/__tests__/linter-translation-api.test.js src/__tests__/linter-page-url.test.js src/__tests__/linter-image-height.test.js src/__tests__/linter-measured-padding.test.js src/__tests__/linter-payment-error.test.js src/__tests__/linter-platform.test.js src/__tests__/linter-react-import.test.js src/__tests__/lucide-icon-names.test.js src/__tests__/lucideIconName.test.js src/__tests__/manifest-actions.test.js src/__tests__/widget-translations.test.js src/__tests__/hooks-translate.test.js src/__tests__/devserver.test.js src/__tests__/host-externals.test.js src/__tests__/datetimepicker.test.js src/__tests__/property-schema-resolve.test.js src/__tests__/theme-components-parity.test.js src/__tests__/navigation-parity.test.js src/__tests__/theme-depth-tokens.test.js src/__tests__/toast-host.test.js src/__tests__/hooks-domain-error-mapping.test.js src/__tests__/linter-datastore-error.test.js src/__tests__/linter-write-gating.test.js src/__tests__/hooks-speech-to-text.test.js src/__tests__/hooks-bound-columns.test.js src/__tests__/hooks-stable-query.test.js src/__tests__/hooks-can-write.test.js"
   },
   "engines": {
     "node": ">=18"