@colixsystems/widget-sdk 0.63.0 → 0.65.0

package/README.md

@@ -53,7 +53,21 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.63.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.65.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.65.0
+
+**Every file record carries `url`, and hand-built file URLs are linted (sc-3589 follow-up).** Two fixes for the same real-world failure: a `FILE` column's image silently not rendering.
+
+- **`url` is now on every file record**, aliasing the absolutized `presigned_url`. The wire field is `presigned_url`, so the intuitive `file.url` read was `undefined` — and because the usual guard is `if (!file.url) return null`, the widget rendered *nothing*, with no error to trace. The alias is added in the filestore client's one shared normalizer, so it applies to `useFilestoreFile(id)` **and every row of `useFilestoreFiles`** — a gallery can render `files.map(f => f.url)` directly. `presigned_url` is unchanged and still present. Requires `@colixsystems/filestore-client` ≥ 0.7.0.
+- **Prefer the top-level `url`:** `const { url } = useFilestoreFile(id)`. The returned `file` is `null` until the fetch resolves (and stays null for an empty `FILE` cell), so `const { file } = …; file.url` throws on the first render. `file.url` is correct only *after* you null-check `file`.
+- **`no-host-api-url` now flags hand-built host paths.** The needles were only `/api/v1`, `/uploads/` and `Authorization: Bearer`, so `` `/api/files/${id}` `` — a route that does not exist — passed clean and shipped. The rule now matches `/api/files/` anywhere (so the origin-prefixed `` `${location.origin}/api/files/${id}` `` is caught too) plus a *quoted* relative `/api/` path for invented prefixes generally. Two deliberate carve-outs: **comments are not scanned**, so documenting the rule in a comment is safe; and an absolute third-party URL that merely contains `/api/` (`https://api.example.com/api/x`) never matches. If a third-party call genuinely needs a *relative* `/api/…` path against an axios `baseURL`, add `// appstudio-lint-ignore no-host-api-url` on that line or the line above.
+
+**Never build a file URL from an id.** Filestore bytes are only reachable through a server-signed token URL, so a client-composed path can never work — always go through `useFilestoreFile`. `CONTRACT.version` → `1.44.0`. Both changes additive; no export changed signature.
+
+### What's new in 0.64.0
+
+**`<DateTimePicker>` themes itself — legible on dark surfaces (sc-3370).** The primitive now derives its colours from the workspace theme on BOTH hosts instead of hardcoding them: the text uses `colors.onSurface`, the border uses `colors.border`, and on web the input's `color-scheme` follows the theme so the browser's built-in date UI (the `yyyy-mm-dd` edit segments and the calendar icon) stays legible on a dark surface. Previously the web input used `color: inherit` with no `color-scheme` and the native trigger set no text colour, so on a dark-themed app the field rendered dark-on-dark and unreadable — with no prop an author could set to fix it. **No prop changed**: the seven-prop contract (`value, onChange, mode, minimumDate, maximumDate, disabled, accessibilityLabel`) is unchanged, and you do NOT style the field yourself — never reach for raw CSS or `document`, which the widget linter rejects. `CONTRACT.version` → `1.43.0`. Behavioural fix, additive.
 
 ### What's new in 0.63.0
 
@@ -230,8 +244,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.
-- `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)`. 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. 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.
+- `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:*`.
 - `useFilestoreFolders({ spaceType, parentFolderId?, q?, enabled? })` → `{ folders, loading, error, refetch }` — the folder-navigation companion to `useFilestoreFiles`; pass `enabled:false` to suspend fetching.
 - `useFilestoreUpload({ spaceType, folderId? })` → `{ 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. 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).
@@ -485,8 +499,9 @@ A widget that works but looks unfinished is only half done. `useTheme()` is the
 - **Build a hierarchy.** A clear title (large, bold, `colors.onSurface`), body text, and muted captions in `colors.onSurfaceMuted` — three weights, not one flat size. Reserve `colors.primary` (with `colors.onPrimary` for text on it) for the single most important action or metric.
 - **Set the theme font on every `Text`.** React Native `Text` does not inherit `fontFamily` from a parent, so a text element that omits it falls back to the system font and ignores the workspace's configured font. Put `theme.typography.fontFamily` on every text style (a shared `StyleSheet` built from `theme` keeps it in one place) and size text with `theme.typography.sizes`.
 - **Contain and elevate.** Wrap a logical unit in a surface: `colors.surface` + padding + `radii.md` + a `colors.border` hairline or a subtle shadow. Use the status roles (`danger / success / warning / info`) for state.
+- **Compose forms — pair fields into rows, don't stack one per row.** Put short, related fields side by side (first + last name, city + postal code, expiry + CVC): a row of `{ flexDirection: 'row', flexWrap: 'wrap', gap: theme.spacing.md }` with each field cell `{ flexGrow: 1, flexBasis: 160 }` splits the width on a wide card and wraps to stacked on a narrow phone — the native-safe way to go multi-column (widgets have no breakpoint hook, so never hard-code fixed columns). Keep wide fields (email, address, notes) full-width, cap it at two–three per row, group a long form into labelled sections, and label every input above it (not placeholder-only).
 - **Respond to touch.** Give every `Pressable` a pressed state via the function-style `style={({ pressed }) => [base, pressed && { opacity: 0.7 }]}`.
-- **Use icons for clarity.** Pair a `lucide-react-native` icon with its label at a consistent size, coloured from the theme.
+- **Use icons for clarity.** Pair a `lucide-react-native` icon with its label at a consistent size, coloured from the theme. The label never repeats the icon as a character — with a `Plus` icon the button says "Add item", never "+ Add item" (that renders a doubled plus).
 - **Use imagery deliberately.** Render pictures with the `Image` primitive (`source` takes a URL or `{ uri }`); resolve workspace assets via `useAsset()`. Give every image a sized, `radii`-clipped container so it never renders as a raw rectangle, and never hardcode a credentialed image URL — expose an `image`-type property instead.
 - **Design the empty, loading, and error states.** A blank box on a fresh install reads as broken — show a short helper line when a list is empty, a calm loading line, and a single human sentence in `colors.danger` on error.
 

package/dist/contract.cjs

@@ -211,10 +211,14 @@ const HOOKS = [
     name: "useFilestoreFiles",
     signature: "useFilestoreFiles({ spaceType, folderId?, q?, type? })",
     description:
-      "Browse the end-user's Filestore files in a project or personal space. " +
-      "The hook resolves owner_id from the host context (tenant for project, " +
-      "app user for personal) — the widget only chooses the space. Reads " +
-      "ctx.filestore.files.list and unwraps { data, meta } to the files array.",
+      "Browse the end-user's Filestore files in a project, personal, or public " +
+      "space. The hook resolves owner_id from the host context (tenant for " +
+      "project/public, app user for personal) — the widget only chooses the " +
+      "space. A public space is world-readable: its files render even for " +
+      "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.",
     returnShape: {
       files: "FilestoreFile[]",
       loading: "boolean",
@@ -236,7 +240,12 @@ const HOOKS = [
       "absolutized by the client so it loads on web AND native. An empty id " +
       "collapses to { file: null, url: null } with no round-trip; a deleted / " +
       "not-found id degrades the same way (url stays null, error carries the " +
-      "wire error) so a display widget shows its fallback instead of crashing.",
+      "wire error) so a display widget shows its fallback instead of crashing. " +
+      "READ THE TOP-LEVEL `url`: `file` is null until the fetch resolves (and " +
+      "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`. " +
+      "NEVER build a file URL by hand from an id — no route serves one.",
     returnShape: {
       file: "FilestoreFile | null",
       url: "string | null",
@@ -295,10 +304,10 @@ const HOOKS = [
     name: "useFilestoreFolders",
     signature: "useFilestoreFolders({ spaceType, parentFolderId?, q?, enabled? })",
     description:
-      "Browse the end-user's Filestore folders in a project or personal space, " +
-      "mirroring useFilestoreFiles for subfolder navigation. The hook resolves " +
-      "owner_id from the host context; pass enabled:false to suspend fetching. " +
-      "Reads ctx.filestore.folders.list and unwraps { data, meta } to the array.",
+      "Browse the end-user's Filestore folders in a project, personal, or public " +
+      "space, mirroring useFilestoreFiles for subfolder navigation. The hook " +
+      "resolves owner_id from the host context; pass enabled:false to suspend " +
+      "fetching. Reads ctx.filestore.folders.list and unwraps { data, meta } to the array.",
     returnShape: {
       folders: "FilestoreFolder[]",
       loading: "boolean",
@@ -823,7 +832,7 @@ const PRIMITIVES = [
   {
     name: "DateTimePicker",
     description:
-      'Cross-platform date / time / datetime picker. `<DateTimePicker value={iso} onChange={iso => …} mode="date" | "time" | "datetime" />`. The value prop and the onChange callback both speak ISO 8601 strings (the datastore wire format) — authors never round-trip through `new Date()`. Web renders the browser\'s native `<input type="date|time|datetime-local">` directly (react-native-web has no mapping for the RN datetimepicker library); native uses @react-native-community/datetimepicker.',
+      'Cross-platform date / time / datetime picker. `<DateTimePicker value={iso} onChange={iso => …} mode="date" | "time" | "datetime" />`. The value prop and the onChange callback both speak ISO 8601 strings (the datastore wire format) — authors never round-trip through `new Date()`. Web renders the browser\'s native `<input type="date|time|datetime-local">` directly (react-native-web has no mapping for the RN datetimepicker library); native uses @react-native-community/datetimepicker. The field themes itself from the workspace theme — text uses `colors.onSurface`, the border `colors.border`, and on web `color-scheme` follows the theme so the browser\'s built-in date UI stays legible on a dark surface; never style it with raw CSS or `document`.',
     rnComponent: "@react-native-community/datetimepicker",
     docsUrl: "https://github.com/react-native-datetimepicker/datetimepicker",
   },
@@ -1090,7 +1099,7 @@ const WIDGET_CONTEXT_SHAPE = {
   },
   filestore: {
     description:
-      "Injected @colixsystems/filestore-client instance — the end-user file archive (project / personal spaces) + BankID file signing. " +
+      "Injected @colixsystems/filestore-client instance — the end-user file archive (project / personal / public spaces) + BankID file signing. " +
       "{ files: { list(query) -> Promise<{ data, meta }>, get(id), upload(formData), update(id, body), remove(id), preview(id) }, " +
       "folders: { list, create, update, remove }, shares: { ... }, trash: { ... }, " +
       "signatures: { initiate(fileId), status(id), cancel(id), verify(id) }, objectUrl(token), fetchObject(token) }. " +
@@ -1209,12 +1218,11 @@ const BUNDLE_EXPORT_CONTRACT = [
 // REQ-WSDK-PLATFORM (docs/design/req-widget-sdk-cross-platform-primitives.md
 // §3.5, §8): `fetch` and `XMLHttpRequest` are NOT banned. Widgets may call
 // third-party APIs directly. Same-origin requests to the host's own
-// `/api/*` surface are rejected at runtime by the WidgetContextProvider's
-// network gate (`no host-api access from widgets`) — the JWT token is
-// never shared with widget code, so the call would 401 anyway; the runtime
-// gate makes the failure mode "blocked" instead of "401 noise". A soft
-// linter warning (`no-host-api-url`) flags obvious host-URL substrings at
-// submission so authors learn the rule statically.
+// `/api/*` surface just fail: widget code never receives the JWT, so they
+// 401 (and an invented route like `/api/files/<id>` 404s). There is no
+// runtime gate — the soft linter warning (`no-host-api-url`) is the only
+// thing that catches it, which is why it flags relative `/api/` literals
+// too, not just the real `/api/v1` prefix.
 const BANNED_APIS = [
   { identifier: "eval", reason: "Arbitrary code evaluation." },
   {
@@ -1305,7 +1313,7 @@ const VETTED_IMPORTS = [
     platforms: ["web", "native"],
     category: "network",
     description:
-      "HTTP client for third-party APIs. Calls to the host's /api/* surface are blocked at runtime — widgets get no JWT token, so use SDK hooks for workspace data.",
+      "HTTP client for third-party APIs. Calls to the host's own /api/* surface do not work — a widget is never given a JWT, so they 401 (and an invented path matches no route at all); use SDK hooks for workspace data.",
   },
   {
     specifier: "date-fns",
@@ -1513,6 +1521,18 @@ const HOST_API_URL_PATTERNS = [
   "/api/v1",
   "/uploads/",
   "Authorization: Bearer",
+  // sc-3589 follow-up — the invented file route, matched ANYWHERE in a literal
+  // so the origin-prefixed spelling (`${location.origin}/api/files/<id>`) is
+  // caught as well as the bare relative one. No route serves this path.
+  "/api/files/",
+  // A QUOTED relative path into the host API — a broader net for invented
+  // prefixes generally. Quote-anchored so an absolute third-party URL that
+  // merely contains "/api/" (https://api.example.com/api/x) does not match.
+  // Comments are blanked before matching, and a legitimate third-party
+  // relative path can opt out with the `appstudio-lint-ignore` directive.
+  '"/api/',
+  "'/api/",
+  "`/api/",
 ];
 
 function deepFreeze(value) {
@@ -1919,7 +1939,28 @@ const CONTRACT = deepFreeze({
   //    default false): declares that the widget renders its own section header,
   //    so the app-builder places it as a whole section without stacking a
   //    heading above it. Additive — existing manifests omit it and read false.
-  version: "1.42.0",
+  // 1.43.0 (sc-3370) — the `<DateTimePicker>` primitive now themes itself from
+  //    the workspace theme on both hosts: text uses `colors.onSurface`, the
+  //    border `colors.border`, and the web input's `color-scheme` follows the
+  //    theme so the browser's built-in date UI stays legible on a dark surface.
+  //    Previously it hardcoded `color: inherit` / an unset scheme (web) and an
+  //    uncoloured trigger (native), rendering dark-on-dark. No prop changed —
+  //    behavioural fix, additive.
+  // 1.44.0 (sc-3589 follow-up) — two FILE-display fixes. (a) The filestore
+  //    client's `withDisplayableUrl` normalizer now aliases the absolutized presigned_url as `url` on
+  //    EVERY file record, so `file.url` works for `useFilestoreFile` AND every
+  //    row of `useFilestoreFiles`. The wire field is `presigned_url`; reading
+  //    the wrong name returned undefined silently, rendering nothing with no
+  //    error. Aliased in the one shared normalizer, not per hook, so the
+  //    single-file and list shapes cannot diverge. `file` is still null while
+  //    loading — the top-level `url` remains the read to prefer.
+  //    (b) `hostApiUrlPatterns` gains `/api/files/` (matched anywhere, so the
+  //    origin-prefixed spelling is caught) plus quote-anchored `/api/` needles
+  //    for invented prefixes generally. The rule now blanks COMMENTS before
+  //    matching, so a comment quoting the bad path is not a finding, and a
+  //    legitimate third-party relative path can opt out with an
+  //    `appstudio-lint-ignore no-host-api-url` comment. Additive.
+  version: "1.44.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -211,10 +211,14 @@ const HOOKS = [
     name: "useFilestoreFiles",
     signature: "useFilestoreFiles({ spaceType, folderId?, q?, type? })",
     description:
-      "Browse the end-user's Filestore files in a project or personal space. " +
-      "The hook resolves owner_id from the host context (tenant for project, " +
-      "app user for personal) — the widget only chooses the space. Reads " +
-      "ctx.filestore.files.list and unwraps { data, meta } to the files array.",
+      "Browse the end-user's Filestore files in a project, personal, or public " +
+      "space. The hook resolves owner_id from the host context (tenant for " +
+      "project/public, app user for personal) — the widget only chooses the " +
+      "space. A public space is world-readable: its files render even for " +
+      "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.",
     returnShape: {
       files: "FilestoreFile[]",
       loading: "boolean",
@@ -236,7 +240,12 @@ const HOOKS = [
       "absolutized by the client so it loads on web AND native. An empty id " +
       "collapses to { file: null, url: null } with no round-trip; a deleted / " +
       "not-found id degrades the same way (url stays null, error carries the " +
-      "wire error) so a display widget shows its fallback instead of crashing.",
+      "wire error) so a display widget shows its fallback instead of crashing. " +
+      "READ THE TOP-LEVEL `url`: `file` is null until the fetch resolves (and " +
+      "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`. " +
+      "NEVER build a file URL by hand from an id — no route serves one.",
     returnShape: {
       file: "FilestoreFile | null",
       url: "string | null",
@@ -295,10 +304,10 @@ const HOOKS = [
     name: "useFilestoreFolders",
     signature: "useFilestoreFolders({ spaceType, parentFolderId?, q?, enabled? })",
     description:
-      "Browse the end-user's Filestore folders in a project or personal space, " +
-      "mirroring useFilestoreFiles for subfolder navigation. The hook resolves " +
-      "owner_id from the host context; pass enabled:false to suspend fetching. " +
-      "Reads ctx.filestore.folders.list and unwraps { data, meta } to the array.",
+      "Browse the end-user's Filestore folders in a project, personal, or public " +
+      "space, mirroring useFilestoreFiles for subfolder navigation. The hook " +
+      "resolves owner_id from the host context; pass enabled:false to suspend " +
+      "fetching. Reads ctx.filestore.folders.list and unwraps { data, meta } to the array.",
     returnShape: {
       folders: "FilestoreFolder[]",
       loading: "boolean",
@@ -823,7 +832,7 @@ const PRIMITIVES = [
   {
     name: "DateTimePicker",
     description:
-      'Cross-platform date / time / datetime picker. `<DateTimePicker value={iso} onChange={iso => …} mode="date" | "time" | "datetime" />`. The value prop and the onChange callback both speak ISO 8601 strings (the datastore wire format) — authors never round-trip through `new Date()`. Web renders the browser\'s native `<input type="date|time|datetime-local">` directly (react-native-web has no mapping for the RN datetimepicker library); native uses @react-native-community/datetimepicker.',
+      'Cross-platform date / time / datetime picker. `<DateTimePicker value={iso} onChange={iso => …} mode="date" | "time" | "datetime" />`. The value prop and the onChange callback both speak ISO 8601 strings (the datastore wire format) — authors never round-trip through `new Date()`. Web renders the browser\'s native `<input type="date|time|datetime-local">` directly (react-native-web has no mapping for the RN datetimepicker library); native uses @react-native-community/datetimepicker. The field themes itself from the workspace theme — text uses `colors.onSurface`, the border `colors.border`, and on web `color-scheme` follows the theme so the browser\'s built-in date UI stays legible on a dark surface; never style it with raw CSS or `document`.',
     rnComponent: "@react-native-community/datetimepicker",
     docsUrl: "https://github.com/react-native-datetimepicker/datetimepicker",
   },
@@ -1090,7 +1099,7 @@ const WIDGET_CONTEXT_SHAPE = {
   },
   filestore: {
     description:
-      "Injected @colixsystems/filestore-client instance — the end-user file archive (project / personal spaces) + BankID file signing. " +
+      "Injected @colixsystems/filestore-client instance — the end-user file archive (project / personal / public spaces) + BankID file signing. " +
       "{ files: { list(query) -> Promise<{ data, meta }>, get(id), upload(formData), update(id, body), remove(id), preview(id) }, " +
       "folders: { list, create, update, remove }, shares: { ... }, trash: { ... }, " +
       "signatures: { initiate(fileId), status(id), cancel(id), verify(id) }, objectUrl(token), fetchObject(token) }. " +
@@ -1209,12 +1218,11 @@ const BUNDLE_EXPORT_CONTRACT = [
 // REQ-WSDK-PLATFORM (docs/design/req-widget-sdk-cross-platform-primitives.md
 // §3.5, §8): `fetch` and `XMLHttpRequest` are NOT banned. Widgets may call
 // third-party APIs directly. Same-origin requests to the host's own
-// `/api/*` surface are rejected at runtime by the WidgetContextProvider's
-// network gate (`no host-api access from widgets`) — the JWT token is
-// never shared with widget code, so the call would 401 anyway; the runtime
-// gate makes the failure mode "blocked" instead of "401 noise". A soft
-// linter warning (`no-host-api-url`) flags obvious host-URL substrings at
-// submission so authors learn the rule statically.
+// `/api/*` surface just fail: widget code never receives the JWT, so they
+// 401 (and an invented route like `/api/files/<id>` 404s). There is no
+// runtime gate — the soft linter warning (`no-host-api-url`) is the only
+// thing that catches it, which is why it flags relative `/api/` literals
+// too, not just the real `/api/v1` prefix.
 const BANNED_APIS = [
   { identifier: "eval", reason: "Arbitrary code evaluation." },
   {
@@ -1305,7 +1313,7 @@ const VETTED_IMPORTS = [
     platforms: ["web", "native"],
     category: "network",
     description:
-      "HTTP client for third-party APIs. Calls to the host's /api/* surface are blocked at runtime — widgets get no JWT token, so use SDK hooks for workspace data.",
+      "HTTP client for third-party APIs. Calls to the host's own /api/* surface do not work — a widget is never given a JWT, so they 401 (and an invented path matches no route at all); use SDK hooks for workspace data.",
   },
   {
     specifier: "date-fns",
@@ -1513,6 +1521,18 @@ const HOST_API_URL_PATTERNS = [
   "/api/v1",
   "/uploads/",
   "Authorization: Bearer",
+  // sc-3589 follow-up — the invented file route, matched ANYWHERE in a literal
+  // so the origin-prefixed spelling (`${location.origin}/api/files/<id>`) is
+  // caught as well as the bare relative one. No route serves this path.
+  "/api/files/",
+  // A QUOTED relative path into the host API — a broader net for invented
+  // prefixes generally. Quote-anchored so an absolute third-party URL that
+  // merely contains "/api/" (https://api.example.com/api/x) does not match.
+  // Comments are blanked before matching, and a legitimate third-party
+  // relative path can opt out with the `appstudio-lint-ignore` directive.
+  '"/api/',
+  "'/api/",
+  "`/api/",
 ];
 
 function deepFreeze(value) {
@@ -1919,7 +1939,28 @@ const CONTRACT = deepFreeze({
   //    default false): declares that the widget renders its own section header,
   //    so the app-builder places it as a whole section without stacking a
   //    heading above it. Additive — existing manifests omit it and read false.
-  version: "1.42.0",
+  // 1.43.0 (sc-3370) — the `<DateTimePicker>` primitive now themes itself from
+  //    the workspace theme on both hosts: text uses `colors.onSurface`, the
+  //    border `colors.border`, and the web input's `color-scheme` follows the
+  //    theme so the browser's built-in date UI stays legible on a dark surface.
+  //    Previously it hardcoded `color: inherit` / an unset scheme (web) and an
+  //    uncoloured trigger (native), rendering dark-on-dark. No prop changed —
+  //    behavioural fix, additive.
+  // 1.44.0 (sc-3589 follow-up) — two FILE-display fixes. (a) The filestore
+  //    client's `withDisplayableUrl` normalizer now aliases the absolutized presigned_url as `url` on
+  //    EVERY file record, so `file.url` works for `useFilestoreFile` AND every
+  //    row of `useFilestoreFiles`. The wire field is `presigned_url`; reading
+  //    the wrong name returned undefined silently, rendering nothing with no
+  //    error. Aliased in the one shared normalizer, not per hook, so the
+  //    single-file and list shapes cannot diverge. `file` is still null while
+  //    loading — the top-level `url` remains the read to prefer.
+  //    (b) `hostApiUrlPatterns` gains `/api/files/` (matched anywhere, so the
+  //    origin-prefixed spelling is caught) plus quote-anchored `/api/` needles
+  //    for invented prefixes generally. The rule now blanks COMMENTS before
+  //    matching, so a comment quoting the bad path is not a finding, and a
+  //    legitimate third-party relative path can opt out with an
+  //    `appstudio-lint-ignore no-host-api-url` comment. Additive.
+  version: "1.44.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/datetimepicker-format.js

@@ -1,9 +1,9 @@
-// REQ-WSDK-PLATFORM §6 — pure date/ISO helpers for the native `<DateTimePicker>`.
+// REQ-WSDK-PLATFORM §6 — pure, RN-free helpers for the `<DateTimePicker>`.
 //
-// Split out of datetimepicker.native.js so the formatting contract can be
+// Split out of the primitive so the formatting + theming contract can be
 // unit-tested without importing react-native / the RN datetimepicker library
 // (neither is installed in this package's node tree). No React, no RN here —
-// just Date math and string shaping.
+// just Date math, string shaping, and a colour-luminance test.
 
 export function parseToDate(value) {
   if (value == null || value === "") return new Date();
@@ -51,3 +51,22 @@ export function formatDisplayLabel(value, mode) {
   if (Number.isNaN(d.getTime())) return String(value);
   return `${formatToIso(d, "date")} ${formatToIso(d, "time")}`;
 }
+
+// Perceived-luminance test for a hex colour (`#rgb` or `#rrggbb`). The web
+// picker uses it to choose a matching `color-scheme` so the browser's built-in
+// date UI (edit segments + calendar icon) stays legible on a dark themed
+// surface. Anything unparseable is treated as light so a light theme is never
+// darkened.
+export function isDarkColor(hex) {
+  if (typeof hex !== "string") return false;
+  let h = hex.trim().replace(/^#/, "");
+  if (h.length === 3) {
+    h = h.split("").map((c) => c + c).join("");
+  }
+  if (h.length !== 6 || /[^0-9a-fA-F]/.test(h)) return false;
+  const r = parseInt(h.slice(0, 2), 16);
+  const g = parseInt(h.slice(2, 4), 16);
+  const b = parseInt(h.slice(4, 6), 16);
+  const luminance = (0.2126 * r + 0.7152 * g + 0.0722 * b) / 255;
+  return luminance < 0.5;
+}

package/dist/datetimepicker.js

@@ -25,6 +25,9 @@
 //                            readers can locate the input by its label.
 
 import React from "react";
+import { useHostTheme } from "./hooks.js";
+import { isDarkColor } from "./datetimepicker-format.js";
+import { DEFAULT_THEME_TOKENS } from "./_theme-tokens.js";
 
 const MODE_TO_INPUT_TYPE = {
   date: "date",
@@ -80,6 +83,7 @@ export function DateTimePicker({
   disabled,
   accessibilityLabel,
 }) {
+  const theme = useHostTheme() || DEFAULT_THEME_TOKENS;
   const effectiveMode = mode === "time" || mode === "datetime" ? mode : "date";
   const inputType = MODE_TO_INPUT_TYPE[effectiveMode];
   const inputValue = _isoToInputValue(value, effectiveMode);
@@ -128,7 +132,13 @@ export function DateTimePicker({
   // Inline styles match the SDK's other web-only primitives — the host's
   // form widgets wrap this in their own labelled field, so the input just
   // needs to look like a normal text input. `cursor: pointer` signals the
-  // whole field is the click affordance (sc-1878).
+  // whole field is the click affordance (sc-1878). Colours come from the
+  // theme so the field is legible on any surface (sc-3370); `colorScheme`
+  // steers the browser's built-in date UI (edit segments + calendar icon).
+  // The scheme keys off the theme's TEXT colour (onSurface, which the host
+  // already picked to contrast the surface) rather than re-deriving dark-vs-
+  // light from the surface with a second luminance formula that could disagree
+  // with the host: light text ⇒ dark surface ⇒ dark scheme.
   const style = {
     boxSizing: "border-box",
     width: "100%",
@@ -136,11 +146,12 @@ export function DateTimePicker({
     padding: "8px 12px",
     fontSize: 16,
     fontFamily: "inherit",
-    color: "inherit",
+    color: theme.colors.onSurface,
     backgroundColor: "transparent",
+    colorScheme: isDarkColor(theme.colors.onSurface) ? "light" : "dark",
     borderWidth: 1,
     borderStyle: "solid",
-    borderColor: "rgba(0, 0, 0, 0.16)",
+    borderColor: theme.colors.border,
     borderRadius: 6,
     outline: "none",
     cursor: disabled ? "default" : "pointer",

package/dist/datetimepicker.native.js

@@ -32,6 +32,8 @@ import {
   formatToIso,
   formatDisplayLabel,
 } from "./datetimepicker-format.js";
+import { useHostTheme } from "./hooks.js";
+import { DEFAULT_THEME_TOKENS } from "./_theme-tokens.js";
 
 const styles = StyleSheet.create({
   trigger: {
@@ -39,7 +41,6 @@ const styles = StyleSheet.create({
     paddingVertical: 8,
     paddingHorizontal: 12,
     borderWidth: 1,
-    borderColor: "rgba(0, 0, 0, 0.16)",
     borderRadius: 6,
     justifyContent: "center",
   },
@@ -57,6 +58,7 @@ export function DateTimePicker({
   disabled,
   accessibilityLabel,
 }) {
+  const theme = useHostTheme() || DEFAULT_THEME_TOKENS;
   const effectiveMode = mode === "time" || mode === "datetime" ? mode : "date";
   const [open, setOpen] = useState(false);
   const dateValue = useMemo(() => parseToDate(value), [value]);
@@ -89,11 +91,21 @@ export function DateTimePicker({
       accessibilityRole: "button",
       accessibilityLabel,
       accessibilityState: { disabled: !!disabled },
-      style: [styles.trigger, disabled && styles.triggerDisabled],
+      // Themed border + text so the trigger is legible on any surface (sc-3370).
+      style: [
+        styles.trigger,
+        { borderColor: theme.colors.border },
+        disabled && styles.triggerDisabled,
+      ],
     },
     React.createElement(
       Text,
-      { style: isEmpty ? styles.placeholder : styles.label },
+      {
+        style: [
+          isEmpty ? styles.placeholder : styles.label,
+          { color: theme.colors.onSurface },
+        ],
+      },
       formatDisplayLabel(value, effectiveMode),
     ),
   );

package/dist/hooks.js

@@ -91,6 +91,17 @@ export function useTheme() {
   return ctx.workspace.theme;
 }
 
+// @internal — reads the host theme WITHOUT throwing when no provider is
+// mounted (returns undefined instead), unlike useTheme() which asserts a
+// widget context. Low-level primitives (DateTimePicker) read it so they stay
+// renderable anywhere, applying their own default tokens on the undefined
+// case. Not part of the public widget hook surface — not re-exported from
+// index.js.
+export function useHostTheme() {
+  const ctx = useContext(HostWidgetContext);
+  return ctx && ctx.workspace ? ctx.workspace.theme : undefined;
+}
+
 /**
  * REQ-THEME-13 — returns the author-set per-widget style values: the object the
  * host delivers under `props.style`, keyed by the style-field names the widget
@@ -1438,8 +1449,10 @@ export function useAssetsByTag(tag, options) {
  * ==========================================================================*/
 
 // Resolve the owner_id a filestore query needs from the host context: a PROJECT
-// space is owned by the tenant (ctx.workspace.id); a PERSONAL space is owned by
-// the signed-in app user (ctx.user.id). The widget only chooses the space.
+// or PUBLIC space is owned by the tenant (ctx.workspace.id); a PERSONAL space is
+// owned by the signed-in app user (ctx.user.id). The widget only chooses the
+// space. PUBLIC is world-readable, so its files resolve even when there is no
+// signed-in user (ctx.workspace.id is set for a logged-out Player visitor too).
 function _filestoreOwnerId(ctx, spaceType) {
   const space = String(spaceType || "project").toUpperCase();
   if (space === "PERSONAL") return (ctx.user && ctx.user.id) || null;
@@ -1535,7 +1548,8 @@ export function useFilestoreFiles(options) {
  * An empty / null id collapses to `{ file: null, url: null }` with no network
  * round-trip; a deleted or not-found id degrades the same way (`url` stays
  * null and `error` carries the wire error) so a display widget shows its
- * fallback instead of crashing.
+ * fallback instead of crashing. Read the top-level `url` — `file` is null
+ * until the fetch resolves, so `file.url` throws on the first render.
  */
 export function useFilestoreFile(fileId) {
   const ctx = useWidgetContextOrThrow("useFilestoreFile");

package/dist/linter.cjs

@@ -69,7 +69,7 @@ const CONTRACT_RULES = CONTRACT.bannedApis.map((b) =>
 // left intact: real code lives there and must still be scanned (`${window}`
 // is a genuine escape). Backslash escapes inside strings/templates are
 // consumed so an escaped quote (`"\""`) doesn't end the literal early.
-function _stripNonCode(source) {
+function _stripNonCode(source, { keepStrings = false } = {}) {
   let out = "";
   const n = source.length;
   let mode = "code"; // code | line | block | sq | dq | tmpl
@@ -84,6 +84,10 @@ function _stripNonCode(source) {
   const blank = (ch) => {
     out += ch === "\n" || ch === "\r" ? ch : " ";
   };
+  // String / template CONTENT: blanked for the banned-identifier scan
+  // (prose must not trip `no-window`), kept for the host-API-URL scan,
+  // whose whole job is to find a URL literal.
+  const str = keepStrings ? keep : blank;
   let i = 0;
   while (i < n) {
     const ch = source[i];
@@ -101,15 +105,15 @@ function _stripNonCode(source) {
         i += 2;
       } else if (ch === "'") {
         mode = "sq";
-        blank(ch);
+        str(ch);
         i += 1;
       } else if (ch === '"') {
         mode = "dq";
-        blank(ch);
+        str(ch);
         i += 1;
       } else if (ch === "`") {
         mode = "tmpl";
-        blank(ch);
+        str(ch);
         i += 1;
       } else if (ch === "{") {
         braceDepth += 1;
@@ -123,7 +127,7 @@ function _stripNonCode(source) {
         ) {
           tmplStack.pop();
           mode = "tmpl";
-          blank(ch);
+          str(ch);
         } else {
           keep(ch);
         }
@@ -153,12 +157,12 @@ function _stripNonCode(source) {
     } else if (mode === "sq" || mode === "dq") {
       const quote = mode === "sq" ? "'" : '"';
       if (ch === "\\") {
-        blank(ch);
-        if (i + 1 < n) blank(nx);
+        str(ch);
+        if (i + 1 < n) str(nx);
         i += 2;
       } else if (ch === quote) {
         mode = "code";
-        blank(ch);
+        str(ch);
         i += 1;
       } else if (ch === "\n") {
         // A bare newline terminates an unterminated string in JS; bail back
@@ -167,18 +171,18 @@ function _stripNonCode(source) {
         keep(ch);
         i += 1;
       } else {
-        blank(ch);
+        str(ch);
         i += 1;
       }
     } else {
       // mode === "tmpl"
       if (ch === "\\") {
-        blank(ch);
-        if (i + 1 < n) blank(nx);
+        str(ch);
+        if (i + 1 < n) str(nx);
         i += 2;
       } else if (ch === "`") {
         mode = "code";
-        blank(ch);
+        str(ch);
         i += 1;
       } else if (ch === "$" && nx === "{") {
         // Enter an expression hole. Remember the brace depth the template
@@ -190,7 +194,7 @@ function _stripNonCode(source) {
         keep(nx);
         i += 2;
       } else {
-        blank(ch);
+        str(ch);
         i += 1;
       }
     }
@@ -332,11 +336,37 @@ function _importRules(source, manifest) {
   return findings;
 }
 
+// Explicit opt-out. A widget legitimately calling a THIRD-PARTY API with a
+// relative path against an `axios` baseURL cannot avoid the substring match,
+// and post-sc-3589 an unavoidable finding burns AI repair turns on correct
+// code. The directive may sit on the offending line or the line above it.
+const HOST_API_URL_IGNORE = "appstudio-lint-ignore no-host-api-url";
+
+function _hostApiUrlIgnoredLines(source) {
+  const ignored = new Set();
+  const lines = source.split(/\r?\n/);
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i];
+    if (!line.includes(HOST_API_URL_IGNORE)) continue;
+    ignored.add(i + 1);
+    // A directive on its OWN line also exempts the line below it. A TRAILING
+    // comment exempts only its own line — otherwise it would silently cover
+    // the next statement, which may be a genuine hand-built host URL.
+    if (/^\s*(\/\/|\/\*|\*)/.test(line)) ignored.add(i + 2);
+  }
+  return ignored;
+}
+
 function _hostApiUrlRules(source) {
   const findings = [];
   const patterns = CONTRACT.hostApiUrlPatterns || [];
-  const lines = source.split(/\r?\n/);
+  const ignored = _hostApiUrlIgnoredLines(source);
+  // Comments are blanked first: a comment or JSDoc line quoting
+  // `/api/files/<id>` — exactly the text the docs tell authors NOT to write —
+  // must not become a blocking publish check.
+  const lines = _stripNonCode(source, { keepStrings: true }).split(/\r?\n/);
   for (let i = 0; i < lines.length; i += 1) {
+    if (ignored.has(i + 1)) continue;
     const line = lines[i];
     for (const needle of patterns) {
       if (line.includes(needle)) {
@@ -344,9 +374,14 @@ function _hostApiUrlRules(source) {
           rule: "no-host-api-url",
           severity: "warning",
           label:
-            `source contains "${needle}" — calls to the AppStudio host API ` +
-            `are blocked at runtime (widgets get no JWT token). Use SDK ` +
-            `hooks for workspace data; \`axios\`/\`fetch\` for third-party APIs.`,
+            `source contains "${needle}" — a widget cannot reach the ` +
+            `AppStudio host API: it is never given a JWT, so the call 401s, ` +
+            `and an invented path like /api/files/<id> matches no route at ` +
+            `all. Read workspace data through SDK hooks (a stored file via ` +
+            `useFilestoreFile(id).url — never a URL you build yourself). ` +
+            `\`axios\`/\`fetch\` remain fine for THIRD-PARTY APIs; if one ` +
+            `genuinely needs a relative /api path, add the comment ` +
+            `"${HOST_API_URL_IGNORE}" on or above the line.`,
           line: i + 1,
           snippet: line.trim().slice(0, 200),
         });

package/dist/linter.js

@@ -70,7 +70,7 @@ const CONTRACT_RULES = CONTRACT.bannedApis.map((b) =>
 // left intact: real code lives there and must still be scanned (`${window}`
 // is a genuine escape). Backslash escapes inside strings/templates are
 // consumed so an escaped quote (`"\""`) doesn't end the literal early.
-function _stripNonCode(source) {
+function _stripNonCode(source, { keepStrings = false } = {}) {
   let out = "";
   const n = source.length;
   let mode = "code"; // code | line | block | sq | dq | tmpl
@@ -85,6 +85,10 @@ function _stripNonCode(source) {
   const blank = (ch) => {
     out += ch === "\n" || ch === "\r" ? ch : " ";
   };
+  // String / template CONTENT: blanked for the banned-identifier scan
+  // (prose must not trip `no-window`), kept for the host-API-URL scan,
+  // whose whole job is to find a URL literal.
+  const str = keepStrings ? keep : blank;
   let i = 0;
   while (i < n) {
     const ch = source[i];
@@ -102,15 +106,15 @@ function _stripNonCode(source) {
         i += 2;
       } else if (ch === "'") {
         mode = "sq";
-        blank(ch);
+        str(ch);
         i += 1;
       } else if (ch === '"') {
         mode = "dq";
-        blank(ch);
+        str(ch);
         i += 1;
       } else if (ch === "`") {
         mode = "tmpl";
-        blank(ch);
+        str(ch);
         i += 1;
       } else if (ch === "{") {
         braceDepth += 1;
@@ -124,7 +128,7 @@ function _stripNonCode(source) {
         ) {
           tmplStack.pop();
           mode = "tmpl";
-          blank(ch);
+          str(ch);
         } else {
           keep(ch);
         }
@@ -154,12 +158,12 @@ function _stripNonCode(source) {
     } else if (mode === "sq" || mode === "dq") {
       const quote = mode === "sq" ? "'" : '"';
       if (ch === "\\") {
-        blank(ch);
-        if (i + 1 < n) blank(nx);
+        str(ch);
+        if (i + 1 < n) str(nx);
         i += 2;
       } else if (ch === quote) {
         mode = "code";
-        blank(ch);
+        str(ch);
         i += 1;
       } else if (ch === "\n") {
         // A bare newline terminates an unterminated string in JS; bail back
@@ -168,18 +172,18 @@ function _stripNonCode(source) {
         keep(ch);
         i += 1;
       } else {
-        blank(ch);
+        str(ch);
         i += 1;
       }
     } else {
       // mode === "tmpl"
       if (ch === "\\") {
-        blank(ch);
-        if (i + 1 < n) blank(nx);
+        str(ch);
+        if (i + 1 < n) str(nx);
         i += 2;
       } else if (ch === "`") {
         mode = "code";
-        blank(ch);
+        str(ch);
         i += 1;
       } else if (ch === "$" && nx === "{") {
         // Enter an expression hole. Remember the brace depth the template
@@ -191,7 +195,7 @@ function _stripNonCode(source) {
         keep(nx);
         i += 2;
       } else {
-        blank(ch);
+        str(ch);
         i += 1;
       }
     }
@@ -204,10 +208,10 @@ function _stripNonCode(source) {
 //
 // REQ-WSDK-PLATFORM: `no-axios-import` is GONE. axios is on the vetted
 // import list now (`CONTRACT.vettedImports`) — widgets may call third-party
-// APIs directly. Calls to the host's own /api/* surface are blocked at
-// runtime by the WidgetContextProvider's network gate; the soft
-// `no-host-api-url` rule below flags obvious host-URL substrings so
-// authors learn the rule statically.
+// APIs directly. Calls to the host's own /api/* surface are not gated at
+// runtime — they simply 401 (widget code never gets the JWT), so the soft
+// `no-host-api-url` rule below is the only thing that catches them, and it
+// flags relative `/api/` literals as well as the real `/api/v1` prefix.
 const EXTRA_RULES = [
   {
     id: "no-auth-store-import",
@@ -369,14 +373,43 @@ function _importRules(source, manifest) {
 }
 
 // REQ-WSDK-PLATFORM §3.5: soft warning when source contains host-API URL
-// substrings. NOT a hard block — false positives are possible (a widget
-// that happens to call a third-party API also located at `/api`). The
-// marketplace review queue surfaces the warning for a human pass.
+// substrings. `severity: "warning"` so a HUMAN-authored submission still
+// publishes and the marketplace review queue flags it for a human pass.
+// sc-3589 — an AI-agent widget has no such review queue, so its publish loop
+// treats every finding (this one included) as a blocking check that drives a
+// repair turn; a lone unrepaired one still publishes with a warning.
+// False positives are possible: the needles are plain substring matches.
+// Explicit opt-out. A widget legitimately calling a THIRD-PARTY API with a
+// relative path against an `axios` baseURL cannot avoid the substring match,
+// and post-sc-3589 an unavoidable finding burns AI repair turns on correct
+// code. The directive may sit on the offending line or the line above it.
+const HOST_API_URL_IGNORE = "appstudio-lint-ignore no-host-api-url";
+
+function _hostApiUrlIgnoredLines(source) {
+  const ignored = new Set();
+  const lines = source.split(/\r?\n/);
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i];
+    if (!line.includes(HOST_API_URL_IGNORE)) continue;
+    ignored.add(i + 1);
+    // A directive on its OWN line also exempts the line below it. A TRAILING
+    // comment exempts only its own line — otherwise it would silently cover
+    // the next statement, which may be a genuine hand-built host URL.
+    if (/^\s*(\/\/|\/\*|\*)/.test(line)) ignored.add(i + 2);
+  }
+  return ignored;
+}
+
 function _hostApiUrlRules(source) {
   const findings = [];
   const patterns = CONTRACT.hostApiUrlPatterns || [];
-  const lines = source.split(/\r?\n/);
+  const ignored = _hostApiUrlIgnoredLines(source);
+  // Comments are blanked first: a comment or JSDoc line quoting
+  // `/api/files/<id>` — exactly the text the docs tell authors NOT to write —
+  // must not become a blocking publish check.
+  const lines = _stripNonCode(source, { keepStrings: true }).split(/\r?\n/);
   for (let i = 0; i < lines.length; i += 1) {
+    if (ignored.has(i + 1)) continue;
     const line = lines[i];
     for (const needle of patterns) {
       if (line.includes(needle)) {
@@ -384,9 +417,14 @@ function _hostApiUrlRules(source) {
           rule: "no-host-api-url",
           severity: "warning",
           label:
-            `source contains "${needle}" — calls to the AppStudio host API ` +
-            `are blocked at runtime (widgets get no JWT token). Use SDK ` +
-            `hooks for workspace data; \`axios\`/\`fetch\` for third-party APIs.`,
+            `source contains "${needle}" — a widget cannot reach the ` +
+            `AppStudio host API: it is never given a JWT, so the call 401s, ` +
+            `and an invented path like /api/files/<id> matches no route at ` +
+            `all. Read workspace data through SDK hooks (a stored file via ` +
+            `useFilestoreFile(id).url — never a URL you build yourself). ` +
+            `\`axios\`/\`fetch\` remain fine for THIRD-PARTY APIs; if one ` +
+            `genuinely needs a relative /api path, add the comment ` +
+            `"${HOST_API_URL_IGNORE}" on or above the line.`,
           line: i + 1,
           snippet: line.trim().slice(0, 200),
         });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.63.0",
+  "version": "0.65.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-schema.test.js src/__tests__/hooks-assets-by-tag.test.js src/__tests__/hooks-filestore-upload.test.js src/__tests__/hooks-mutation.test.js src/__tests__/hooks-record-permissions.test.js src/__tests__/hooks-geolocation.test.js src/__tests__/hooks-subscription.test.js src/__tests__/linter-users-scope.test.js src/__tests__/linter-comments.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__/devserver.test.js src/__tests__/host-externals.test.js src/__tests__/datetimepicker.test.js src/__tests__/property-schema-resolve.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-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-record-permissions.test.js src/__tests__/hooks-geolocation.test.js src/__tests__/hooks-subscription.test.js src/__tests__/linter-users-scope.test.js src/__tests__/linter-comments.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__/devserver.test.js src/__tests__/host-externals.test.js src/__tests__/datetimepicker.test.js src/__tests__/property-schema-resolve.test.js"
   },
   "engines": {
     "node": ">=18"