@colixsystems/widget-sdk 0.167.0 → 0.169.0

package/README.md

@@ -73,7 +73,18 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.167.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.169.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.169.0 (contract 1.130.0)
+
+**Widgets can create folders and copy files, including between spaces.** Two new hooks over `ctx.filestore`:
+
+- `useFilestoreCreateFolder({ spaceType, parentFolderId? })` → `{ createFolder, creating, error, lastCreated }`. `createFolder(name, { parentFolderId? })` resolves to the new folder row; `parentFolderId` omitted or `null` places it at the space root. Refetch your `useFilestoreFolders` afterwards to show it.
+- `useFilestoreCopy()` → `{ copy, copying, error, lastCopied }`. `copy(fileId, { spaceType, folderId?, name? })` duplicates a file into any space the user may add files to — project, public, or their own personal space — and resolves to the **new** file row with its own `id` and `url`. `spaceType` names the destination and is required. The bytes are duplicated server-side, so the copy and its source are independent afterwards. A name already taken at the destination lands as `name (2).ext` and never replaces the existing file.
+
+The public space keeps its usual gate: copying into it needs the same upload access the workspace operator grants for uploads, and creating a folder there needs the right to manage that space, so an app user's public `createFolder()` is refused unless they were given it. Copying into the user's own personal space works whenever they may download the source.
+
+Refusals keep the usual shape: branch on `err.status`, with the server's code at `err.details.code`. The copy-specific codes are `FILE_COPY_NOT_PERMITTED` (the user may only view the source), `UPLOAD_NOT_PERMITTED` (the destination refuses the add), `STORAGE_QUOTA_EXCEEDED` (413) and `FILE_PROCESSING` (409, a video still being processed). Both hooks need the `files.write:*` scope and behave identically on the web Player and the native export. Needs `@colixsystems/filestore-client` 0.10.0, which adds `files.copy(id, body)`.
 
 ### What's new in 0.167.0 (contract 1.129.0)
 
@@ -93,7 +104,7 @@ Render an **assistant** message with `<RichText value={m.content} stripLegacyHtm
 A binding may now carry an opacity: `"theme:colors.primary/20"` is the primary brand colour at 20%.
 
 - **`parseThemeColorTokenRef(value)` / `formatThemeColorTokenRef(path, percent)`** publish the grammar beside the existing `isThemeColorTokenRef` predicate. The BARE form inherits whatever opacity the token itself carries — a workspace may author a translucent brand colour — so `/100` is a real value, not a redundant spelling: it is how "opaque, whatever the brand does" is said. One opacity has one spelling otherwise (no leading zeros, nothing above 100).
-- **`withHexAlpha(hex, percent)` / `hexAlphaPercent(hex)`** are the percent ↔ alpha-byte conversion the Studio's opacity control and both hosts' resolver share, so the 20% a panel reads back is the 20% a render paints.
+- **`withHexAlpha(hex, percent)` / `hexAlphaPercent(hex)`** are the percent ↔ alpha-byte conversion, so the 20% a panel reads back is the 20% a render paints. The Studio's `frontend/src/utils/color.js` keeps its own copy of this maths rather than importing it — that module is reached by a `node --test` suite, and the SDK is a Vite alias with no node resolution — and the two are pinned equal by the SDK's suite.
 - **An authored opacity replaces the token's.** With none authored the token is handed back verbatim, including a token that is itself translucent — reading the bare form as 100 would quietly paint a see-through brand colour solid.
 - **A token resolving to a non-hex colour stays opaque** — alpha cannot be applied without rewriting the author's notation — and the Studio disables the opacity control for that case rather than lying about it.
 - **Nothing changes for a widget author.** The host still hands your code an ordinary colour string; it is simply `#RRGGBBAA` when an opacity was authored.
@@ -1593,7 +1604,7 @@ Also: `useFileSignatures(fileIds)` is now **self-scoped** (the caller's own sign
 **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. 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.
+- `useFilestoreFolders({ spaceType, parentFolderId?, q?, enabled? })` → `{ folders, loading, error, refetch }` — the folder-navigation companion to `useFilestoreFiles`; pass `enabled:false` to suspend fetching. (Folder creation and file copy arrived later, in 0.169.0 — see above.)
 - `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

@@ -1217,6 +1217,56 @@ const HOOKS = [
     requiredContextSlice: ["filestore.folders"],
     scopes: ["files.read:*"],
   },
+  {
+    name: "useFilestoreCreateFolder",
+    signature: "useFilestoreCreateFolder({ spaceType, parentFolderId })",
+    optionalArgs: ["parentFolderId"],
+    description:
+      "Create a folder in the end-user's Filestore space. The widget passes the " +
+      "SPACE (`{ spaceType, parentFolderId? }`); the hook resolves owner_id from " +
+      "the host context and posts `{ name, space_type, owner_id, parent_folder_id }` " +
+      "through ctx.filestore.folders.create. `createFolder(name, { parentFolderId? })` " +
+      "resolves to the created folder row or throws the wire error: 422 for an " +
+      "invalid name, 404 for a parent that is not in this space, 403/404 when the " +
+      "caller may not add a folder there (the server's FOLDER_CREATE_NOT_PERMITTED " +
+      "is at `err.details.code`). In the public space only managers of that space " +
+      "may create folders. Refetch useFilestoreFolders afterwards to show it.",
+    returnShape: {
+      createFolder: "(name, { parentFolderId? }) => Promise<FilestoreFolder>",
+      creating: "boolean",
+      error: "Error | null",
+      lastCreated: "FilestoreFolder | null",
+    },
+    requiredContextSlice: ["filestore.folders"],
+    scopes: ["files.write:*"],
+  },
+  {
+    name: "useFilestoreCopy",
+    signature: "useFilestoreCopy()",
+    description:
+      "Copy a Filestore file into any space and folder the caller may add files " +
+      "to, including ACROSS spaces (project, public, and the signed-in user's " +
+      "personal space). `copy(fileId, { spaceType, folderId?, name? })` names the " +
+      "DESTINATION (spaceType is required); the hook resolves its owner_id from " +
+      "the host context and posts through ctx.filestore.files.copy. Resolves to " +
+      "the NEW file row (its own id and url) — the source is untouched and the " +
+      "bytes are duplicated, so later changes to one never affect the other. A " +
+      "name already taken at the destination lands as \"name (2).ext\" instead of " +
+      "replacing it. Copying INTO public needs the same operator upload grant as " +
+      "uploading there. Errors (code at `err.details.code`): 404 source not visible; " +
+      "403 FILE_COPY_NOT_PERMITTED when the caller may only view the source; " +
+      "403/404 UPLOAD_NOT_PERMITTED when the destination refuses the add; 413 " +
+      "STORAGE_QUOTA_EXCEEDED when the destination space is full; 409 " +
+      "FILE_PROCESSING while a video is still being processed.",
+    returnShape: {
+      copy: "(fileId, { spaceType, folderId?, name? }) => Promise<FilestoreFile>",
+      copying: "boolean",
+      error: "Error | null",
+      lastCopied: "FilestoreFile | null",
+    },
+    requiredContextSlice: ["filestore.files"],
+    scopes: ["files.write:*"],
+  },
   {
     name: "useFileSignature",
     signature: "useFileSignature(fileId, existingSignatureId)",
@@ -2692,10 +2742,10 @@ const WIDGET_CONTEXT_SHAPE = {
   filestore: {
     description:
       "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) }, " +
+      "{ files: { list(query) -> Promise<{ data, meta }>, get(id), upload(formData), update(id, body), copy(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) }. " +
-      "Backs useFilestoreFiles() + useFilestoreFolders() + useFileSignature(). Optional — a host without an end-user filestore omits it and those hooks throw a clear error.",
+      "Backs useFilestoreFiles() + useFilestoreFolders() + useFilestoreCreateFolder() + useFilestoreCopy() + useFileSignature(). Optional — a host without an end-user filestore omits it and those hooks throw a clear error.",
     required: false,
     fields: { files: "object", folders: "object", shares: "object", signatures: "object" },
   },
@@ -4539,10 +4589,10 @@ const CONTRACT = deepFreeze({
   //    field bound, so "our brand colour at 20%" forced the author back to a
   //    frozen hex, which then stopped following a rebrand — the exact thing
   //    binding exists to prevent. `parseThemeColorTokenRef` /
-  //    `formatThemeColorTokenRef` publish the grammar and
+  //    `formatThemeColorTokenRef` publish the grammar, and
   //    `withHexAlpha` / `hexAlphaPercent` the percent-to-byte conversion the
-  //    Studio's control and both hosts' resolver share, so 20% authored is 20%
-  //    painted. The BARE form inherits the token's own opacity (a brand colour
+  //    Studio's control and both hosts' resolver answer alike, so 20% authored
+  //    is 20% painted. The BARE form inherits the token's own opacity (a brand colour
   //    may be authored translucent), which makes `/100` a real value rather
   //    than a redundant spelling: it is how "opaque, whatever the brand does"
   //    is said. Additive: an unsuffixed binding parses and resolves exactly as
@@ -4553,7 +4603,11 @@ const CONTRACT = deepFreeze({
   // it removed every `<...>`, so an AI reply lost `Promise<void>`. The
   // emphasis grammar now follows CommonMark flanking rules, so `created_at`
   // keeps its underscore and `2 * 4` keeps its asterisk.
-  version: "1.129.0",
+  // 1.130.0: additive (sc-9057) — `useFilestoreCreateFolder` and
+  // `useFilestoreCopy`. Widgets can now create Filestore folders and copy a
+  // file into another folder or space (project / public / personal); the
+  // filestore client gains `files.copy`.
+  version: "1.130.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -1217,6 +1217,56 @@ const HOOKS = [
     requiredContextSlice: ["filestore.folders"],
     scopes: ["files.read:*"],
   },
+  {
+    name: "useFilestoreCreateFolder",
+    signature: "useFilestoreCreateFolder({ spaceType, parentFolderId })",
+    optionalArgs: ["parentFolderId"],
+    description:
+      "Create a folder in the end-user's Filestore space. The widget passes the " +
+      "SPACE (`{ spaceType, parentFolderId? }`); the hook resolves owner_id from " +
+      "the host context and posts `{ name, space_type, owner_id, parent_folder_id }` " +
+      "through ctx.filestore.folders.create. `createFolder(name, { parentFolderId? })` " +
+      "resolves to the created folder row or throws the wire error: 422 for an " +
+      "invalid name, 404 for a parent that is not in this space, 403/404 when the " +
+      "caller may not add a folder there (the server's FOLDER_CREATE_NOT_PERMITTED " +
+      "is at `err.details.code`). In the public space only managers of that space " +
+      "may create folders. Refetch useFilestoreFolders afterwards to show it.",
+    returnShape: {
+      createFolder: "(name, { parentFolderId? }) => Promise<FilestoreFolder>",
+      creating: "boolean",
+      error: "Error | null",
+      lastCreated: "FilestoreFolder | null",
+    },
+    requiredContextSlice: ["filestore.folders"],
+    scopes: ["files.write:*"],
+  },
+  {
+    name: "useFilestoreCopy",
+    signature: "useFilestoreCopy()",
+    description:
+      "Copy a Filestore file into any space and folder the caller may add files " +
+      "to, including ACROSS spaces (project, public, and the signed-in user's " +
+      "personal space). `copy(fileId, { spaceType, folderId?, name? })` names the " +
+      "DESTINATION (spaceType is required); the hook resolves its owner_id from " +
+      "the host context and posts through ctx.filestore.files.copy. Resolves to " +
+      "the NEW file row (its own id and url) — the source is untouched and the " +
+      "bytes are duplicated, so later changes to one never affect the other. A " +
+      "name already taken at the destination lands as \"name (2).ext\" instead of " +
+      "replacing it. Copying INTO public needs the same operator upload grant as " +
+      "uploading there. Errors (code at `err.details.code`): 404 source not visible; " +
+      "403 FILE_COPY_NOT_PERMITTED when the caller may only view the source; " +
+      "403/404 UPLOAD_NOT_PERMITTED when the destination refuses the add; 413 " +
+      "STORAGE_QUOTA_EXCEEDED when the destination space is full; 409 " +
+      "FILE_PROCESSING while a video is still being processed.",
+    returnShape: {
+      copy: "(fileId, { spaceType, folderId?, name? }) => Promise<FilestoreFile>",
+      copying: "boolean",
+      error: "Error | null",
+      lastCopied: "FilestoreFile | null",
+    },
+    requiredContextSlice: ["filestore.files"],
+    scopes: ["files.write:*"],
+  },
   {
     name: "useFileSignature",
     signature: "useFileSignature(fileId, existingSignatureId)",
@@ -2688,10 +2738,10 @@ const WIDGET_CONTEXT_SHAPE = {
   filestore: {
     description:
       "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) }, " +
+      "{ files: { list(query) -> Promise<{ data, meta }>, get(id), upload(formData), update(id, body), copy(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) }. " +
-      "Backs useFilestoreFiles() + useFilestoreFolders() + useFileSignature(). Optional — a host without an end-user filestore omits it and those hooks throw a clear error.",
+      "Backs useFilestoreFiles() + useFilestoreFolders() + useFilestoreCreateFolder() + useFilestoreCopy() + useFileSignature(). Optional — a host without an end-user filestore omits it and those hooks throw a clear error.",
     required: false,
     fields: { files: "object", folders: "object", shares: "object", signatures: "object" },
   },
@@ -4535,10 +4585,10 @@ const CONTRACT = deepFreeze({
   //    field bound, so "our brand colour at 20%" forced the author back to a
   //    frozen hex, which then stopped following a rebrand — the exact thing
   //    binding exists to prevent. `parseThemeColorTokenRef` /
-  //    `formatThemeColorTokenRef` publish the grammar and
+  //    `formatThemeColorTokenRef` publish the grammar, and
   //    `withHexAlpha` / `hexAlphaPercent` the percent-to-byte conversion the
-  //    Studio's control and both hosts' resolver share, so 20% authored is 20%
-  //    painted. The BARE form inherits the token's own opacity (a brand colour
+  //    Studio's control and both hosts' resolver answer alike, so 20% authored
+  //    is 20% painted. The BARE form inherits the token's own opacity (a brand colour
   //    may be authored translucent), which makes `/100` a real value rather
   //    than a redundant spelling: it is how "opaque, whatever the brand does"
   //    is said. Additive: an unsuffixed binding parses and resolves exactly as
@@ -4549,7 +4599,11 @@ const CONTRACT = deepFreeze({
   // it removed every `<...>`, so an AI reply lost `Promise<void>`. The
   // emphasis grammar now follows CommonMark flanking rules, so `created_at`
   // keeps its underscore and `2 * 4` keeps its asterisk.
-  version: "1.129.0",
+  // 1.130.0: additive (sc-9057) — `useFilestoreCreateFolder` and
+  // `useFilestoreCopy`. Widgets can now create Filestore folders and copy a
+  // file into another folder or space (project / public / personal); the
+  // filestore client gains `files.copy`.
+  version: "1.130.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/hooks.js

@@ -3850,7 +3850,8 @@ export function useAssetsByTag(tag, options) {
  * FILESTORE CLIENT — ctx.filestore (@colixsystems/filestore-client)
  *
  * The end-user file archive (project / personal spaces) + BankID file signing.
- * Covers: useFilestoreFiles, useFileSignature.
+ * Covers: useFilestoreFiles, useFilestoreFolders, useFilestoreCreateFolder,
+ * useFilestoreCopy, useFilestoreUpload, useFileSignature.
  * ==========================================================================*/
 
 // Resolve the owner_id a filestore query needs from the host context: a PROJECT
@@ -4302,6 +4303,153 @@ export function useFilestoreFolders(options) {
   return { folders, loading, error, refetch };
 }
 
+/**
+ * Create a folder in the end-user's Filestore space. Returns `{ createFolder,
+ * creating, error, lastCreated }`. The widget passes the SPACE (`{ spaceType,
+ * parentFolderId? }`); the hook resolves owner_id from the host context and
+ * posts `{ name, space_type, owner_id, parent_folder_id }` through
+ * `ctx.filestore.folders.create`.
+ *
+ * `createFolder(name, { parentFolderId? })` resolves to the created folder row
+ * or throws the wire error: 422 for an invalid name, 404 for a parent that is
+ * not in this space, and 403/404 when the caller may not add a folder there
+ * (403 when they can see the position). The server's
+ * `FOLDER_CREATE_NOT_PERMITTED` is at `err.details.code`.
+ */
+export function useFilestoreCreateFolder(options) {
+  const ctx = useWidgetContextOrThrow("useFilestoreCreateFolder");
+  if (
+    !ctx.filestore ||
+    !ctx.filestore.folders ||
+    typeof ctx.filestore.folders.create !== "function"
+  ) {
+    throw new Error(
+      "useFilestoreCreateFolder: host did not inject a filestore client (ctx.filestore.folders.create)",
+    );
+  }
+  const { spaceType = "project", parentFolderId: defaultParentId = null } =
+    options || {};
+  const ownerId = _filestoreOwnerId(ctx, spaceType);
+
+  const [creating, setCreating] = useState(false);
+  const [error, setError] = useState(null);
+  const [lastCreated, setLastCreated] = useState(null);
+
+  const foldersRef = useRef(ctx.filestore.folders);
+  foldersRef.current = ctx.filestore.folders;
+
+  const createFolder = useCallback(
+    async (name, overrides) => {
+      if (typeof name !== "string" || name.trim().length === 0) {
+        throw new Error("useFilestoreCreateFolder: name is required");
+      }
+      if (!ownerId) {
+        const err = new Error("Sign in to create a folder");
+        setError(err);
+        throw err;
+      }
+      const parentFolderId =
+        overrides &&
+        Object.prototype.hasOwnProperty.call(overrides, "parentFolderId")
+          ? overrides.parentFolderId
+          : defaultParentId;
+      const body = {
+        name: name.trim(),
+        space_type: String(spaceType || "project").toUpperCase(),
+        owner_id: ownerId,
+      };
+      if (parentFolderId) body.parent_folder_id = parentFolderId;
+      setCreating(true);
+      setError(null);
+      try {
+        const created = await foldersRef.current.create(body);
+        setLastCreated(created || null);
+        setCreating(false);
+        return created;
+      } catch (err) {
+        setError(err);
+        setCreating(false);
+        throw err;
+      }
+    },
+    [ownerId, defaultParentId, spaceType],
+  );
+
+  return { createFolder, creating, error, lastCreated };
+}
+
+/**
+ * Copy a Filestore file into any space and folder the caller may add files
+ * to — including ACROSS spaces (project, public, the user's personal space).
+ * Returns `{ copy, copying, error, lastCopied }`.
+ *
+ * `copy(fileId, { spaceType, folderId?, name? })` names the DESTINATION;
+ * `spaceType` is required. The hook resolves the destination owner_id the same
+ * way the upload hook does and posts through `ctx.filestore.files.copy`. It
+ * resolves to the NEW file row (its own id and url); the source is untouched.
+ * A name already taken at the destination lands as "name (2).ext" rather than
+ * replacing that file.
+ *
+ * Errors: 404 when the source is not visible, 403 `FILE_COPY_NOT_PERMITTED`
+ * when it is view-only, 403/404 `UPLOAD_NOT_PERMITTED` when the destination
+ * refuses the add, 413 `STORAGE_QUOTA_EXCEEDED` when the destination space is
+ * full, 409 `FILE_PROCESSING` while a video is still being processed. The code
+ * is at `err.details.code`.
+ */
+export function useFilestoreCopy() {
+  const ctx = useWidgetContextOrThrow("useFilestoreCopy");
+  if (
+    !ctx.filestore ||
+    !ctx.filestore.files ||
+    typeof ctx.filestore.files.copy !== "function"
+  ) {
+    throw new Error(
+      "useFilestoreCopy: host did not inject a filestore client (ctx.filestore.files.copy)",
+    );
+  }
+
+  const [copying, setCopying] = useState(false);
+  const [error, setError] = useState(null);
+  const [lastCopied, setLastCopied] = useState(null);
+
+  const ctxRef = useRef(ctx);
+  ctxRef.current = ctx;
+
+  const copy = useCallback(async (fileId, destination) => {
+    if (!fileId) throw new Error("useFilestoreCopy: fileId is required");
+    const { spaceType, folderId, name } = destination || {};
+    if (!spaceType) {
+      throw new Error("useFilestoreCopy: destination spaceType is required");
+    }
+    const ownerId = _filestoreOwnerId(ctxRef.current, spaceType);
+    if (!ownerId) {
+      const err = new Error("Sign in to copy files");
+      setError(err);
+      throw err;
+    }
+    const body = {
+      space_type: String(spaceType).toUpperCase(),
+      owner_id: ownerId,
+    };
+    if (folderId) body.folder_id = folderId;
+    if (name) body.name = name;
+    setCopying(true);
+    setError(null);
+    try {
+      const created = await ctxRef.current.filestore.files.copy(fileId, body);
+      setLastCopied(created || null);
+      setCopying(false);
+      return created;
+    } catch (err) {
+      setError(err);
+      setCopying(false);
+      throw err;
+    }
+  }, []);
+
+  return { copy, copying, error, lastCopied };
+}
+
 /**
  * Drive a BankID signing flow for one Filestore file. Returns
  * `{ status, qr, autoStartToken, message, signerName, signedAt, verdict,

package/dist/host.js

@@ -74,6 +74,9 @@ export {
 // SIDEBAR local menu hangs in the rail and the drawer. The compiler asks it
 // once per screen at build time and the Player once per render, so the two
 // chromes derive the same tree from the same code.
+// REQ-NAV-LOCAL (sc-8901): `resolveLocalNavModel` answers WHICH model a page
+// wears in one device view, so the same menu can be a bottom bar on a phone and
+// unfold in the rail on a desktop.
 export {
   normaliseNavigation,
   menuItemCap,
@@ -94,6 +97,8 @@ export {
   DEFAULT_TOP_STRIPE_HEIGHT_PX,
   DEFAULT_TOP_STRIPE_PADDING_X_PX,
   resolveSidebarUnfold,
+  resolveLocalNavModel,
+  drawsLocalNavAnywhere,
 } from "./navigation.js";
 
 // sc-5717: the codec behind `useWidgetRoute()` — how a widget's own internal

package/dist/index.js

@@ -44,6 +44,8 @@ export {
   useFilestoreUpload,
   usePdfExport,
   useFilestoreFolders,
+  useFilestoreCreateFolder,
+  useFilestoreCopy,
   useFileSignature,
   useFileSignatures,
   useFileRoster,

package/dist/index.native.js

@@ -44,6 +44,8 @@ export {
   useFilestoreUpload,
   usePdfExport,
   useFilestoreFolders,
+  useFilestoreCreateFolder,
+  useFilestoreCopy,
   useFileSignature,
   useFileSignatures,
   useFileRoster,

package/dist/navigation.cjs

@@ -675,6 +675,64 @@ function resolveSidebarUnfold(input) {
   return { under: section.key, items: marked, standalone: true };
 }
 
+/**
+ * REQ-NAV-LOCAL (sc-8901) — which local-navigation model a page wears in ONE
+ * device view, so the same saved menu can be a bottom bar on a phone and unfold
+ * in the rail on a desktop.
+ *
+ * `local_nav` is the MOBILE value and the base of the cascade: a page authored
+ * before the wider views existed leaves both of them unset and therefore
+ * renders identically at every width. The cascade is REQ-LAY-07's — the one the
+ * layout grid and every responsive widget prop already use — because a page's
+ * chrome and its content must not disagree about what a tablet is.
+ *
+ * The vocabulary stays the API's: any non-empty string is a model and the
+ * host's own switch decides what it can draw, so a kind a newer backend allows
+ * cascades correctly here instead of being flattened to `NONE` on the way.
+ *
+ * @param {object|null|undefined} page — a page row carrying `local_nav` and,
+ *   optionally, `local_nav_tablet` / `local_nav_desktop`.
+ * @param {"mobile"|"tablet"|"desktop"} view — the device view being drawn.
+ * @returns {string} the model for that view; `NONE` when the page sets none.
+ */
+function resolveLocalNavModel(page, view) {
+  const at = (key) => {
+    const value = isPlainObject(page) ? page[key] : null;
+    return typeof value === "string" && value ? value : null;
+  };
+  const mobile = at("local_nav") || "NONE";
+  if (view === "desktop") {
+    return at("local_nav_desktop") || at("local_nav_tablet") || mobile;
+  }
+  if (view === "tablet") return at("local_nav_tablet") || mobile;
+  return mobile;
+}
+
+// sc-8901: the three device views a local bar can differ across — REQ-LAY-07's
+// own list, so a page's chrome and its content classify a width alike. Ordered
+// narrowest first, which is also the cascade's direction.
+const LOCAL_NAV_VIEWS = ["mobile", "tablet", "desktop"];
+
+/**
+ * REQ-NAV-LOCAL (sc-8901) — does this page draw a local bar in ANY device view?
+ *
+ * The saved-menu reference is shared by all three views, so it is required — and
+ * resolved onto the wire — as soon as one of them draws. Asking
+ * `local_nav !== "NONE"` alone would miss a page that carries a bar only on the
+ * wider views.
+ *
+ * Beside the cascade it is derived from, so the API rule, the export's screen
+ * bake and Copy Workspace cannot disagree about which pages have a bar.
+ *
+ * @param {object|null|undefined} page — a page row.
+ * @returns {boolean}
+ */
+function drawsLocalNavAnywhere(page) {
+  return LOCAL_NAV_VIEWS.some(
+    (view) => resolveLocalNavModel(page, view) !== "NONE",
+  );
+}
+
 // REQ-THEME-LOOK: the divider's width in px, bounded HERE so both hosts inherit
 // one range. The export clamped it on its way into the StyleSheet
 // (`coerceBorderWidth(...) ?? 1`) where the Player passed any finite number
@@ -711,4 +769,4 @@ function borderWidthOr(...values) {
   return BORDER_WIDTH_MIN;
 }
 
-module.exports = { normaliseNavigation, menuItemCap, resolveFooterTokens, resolveSidebarTokens, resolveTopStripeLayout, resolveTopBarTokens, topStripeShowKey, TOP_STRIPE_ALWAYS_SHOWN_SLOTS, TOP_STRIPE_SLOTS, MIN_TOP_STRIPE_HEIGHT_PX, MAX_TOP_STRIPE_HEIGHT_PX, MIN_TOP_STRIPE_PADDING_X_PX, MAX_TOP_STRIPE_PADDING_X_PX, MAX_TOP_STRIPE_OFFSET_Y_PX, DEFAULT_TOP_STRIPE_HEIGHT_PX, DEFAULT_TOP_STRIPE_PADDING_X_PX, resolveSidebarUnfold };
+module.exports = { normaliseNavigation, menuItemCap, resolveFooterTokens, resolveSidebarTokens, resolveTopStripeLayout, resolveTopBarTokens, topStripeShowKey, TOP_STRIPE_ALWAYS_SHOWN_SLOTS, TOP_STRIPE_SLOTS, MIN_TOP_STRIPE_HEIGHT_PX, MAX_TOP_STRIPE_HEIGHT_PX, MIN_TOP_STRIPE_PADDING_X_PX, MAX_TOP_STRIPE_PADDING_X_PX, MAX_TOP_STRIPE_OFFSET_Y_PX, DEFAULT_TOP_STRIPE_HEIGHT_PX, DEFAULT_TOP_STRIPE_PADDING_X_PX, resolveSidebarUnfold, resolveLocalNavModel, drawsLocalNavAnywhere };

package/dist/navigation.js

@@ -666,6 +666,64 @@ export function resolveSidebarUnfold(input) {
   return { under: section.key, items: marked, standalone: true };
 }
 
+/**
+ * REQ-NAV-LOCAL (sc-8901) — which local-navigation model a page wears in ONE
+ * device view, so the same saved menu can be a bottom bar on a phone and unfold
+ * in the rail on a desktop.
+ *
+ * `local_nav` is the MOBILE value and the base of the cascade: a page authored
+ * before the wider views existed leaves both of them unset and therefore
+ * renders identically at every width. The cascade is REQ-LAY-07's — the one the
+ * layout grid and every responsive widget prop already use — because a page's
+ * chrome and its content must not disagree about what a tablet is.
+ *
+ * The vocabulary stays the API's: any non-empty string is a model and the
+ * host's own switch decides what it can draw, so a kind a newer backend allows
+ * cascades correctly here instead of being flattened to `NONE` on the way.
+ *
+ * @param {object|null|undefined} page — a page row carrying `local_nav` and,
+ *   optionally, `local_nav_tablet` / `local_nav_desktop`.
+ * @param {"mobile"|"tablet"|"desktop"} view — the device view being drawn.
+ * @returns {string} the model for that view; `NONE` when the page sets none.
+ */
+export function resolveLocalNavModel(page, view) {
+  const at = (key) => {
+    const value = isPlainObject(page) ? page[key] : null;
+    return typeof value === "string" && value ? value : null;
+  };
+  const mobile = at("local_nav") || "NONE";
+  if (view === "desktop") {
+    return at("local_nav_desktop") || at("local_nav_tablet") || mobile;
+  }
+  if (view === "tablet") return at("local_nav_tablet") || mobile;
+  return mobile;
+}
+
+// sc-8901: the three device views a local bar can differ across — REQ-LAY-07's
+// own list, so a page's chrome and its content classify a width alike. Ordered
+// narrowest first, which is also the cascade's direction.
+const LOCAL_NAV_VIEWS = ["mobile", "tablet", "desktop"];
+
+/**
+ * REQ-NAV-LOCAL (sc-8901) — does this page draw a local bar in ANY device view?
+ *
+ * The saved-menu reference is shared by all three views, so it is required — and
+ * resolved onto the wire — as soon as one of them draws. Asking
+ * `local_nav !== "NONE"` alone would miss a page that carries a bar only on the
+ * wider views.
+ *
+ * Beside the cascade it is derived from, so the API rule, the export's screen
+ * bake and Copy Workspace cannot disagree about which pages have a bar.
+ *
+ * @param {object|null|undefined} page — a page row.
+ * @returns {boolean}
+ */
+export function drawsLocalNavAnywhere(page) {
+  return LOCAL_NAV_VIEWS.some(
+    (view) => resolveLocalNavModel(page, view) !== "NONE",
+  );
+}
+
 // REQ-THEME-LOOK: the divider's width in px, bounded HERE so both hosts inherit
 // one range. The export clamped it on its way into the StyleSheet
 // (`coerceBorderWidth(...) ?? 1`) where the Player passed any finite number

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.167.0",
+  "version": "0.169.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "homepage": "https://github.com/Colix-AB/AppStudio",
   "type": "module",