Docs: clarify ZIP download flow and add streaming

Update documentation and implementation to reflect that space ZIP downloads and hosted sharing fetch archives from the authenticated backend `folder_download` endpoint instead of creating them inline. Document that app-file fetches percent-decode URL path segments before normalization so browser-encoded filenames (spaces, brackets, unicode, `#`, `?`) resolve correctly while rejecting encoded separators (`%2F`, `%5C`). Replace host `zip` binary with in-process `archiver`

Author: frdel

app/L0/_all/mod/_core/documentation/docs/app/spaces-and-widgets.md

@@ -57,10 +57,10 @@ The current-space share button opens a spaces-owned modal that keeps local impor
 
 Current behaviors:
 
-- `Download ZIP` always exports the current `~/spaces/<spaceId>/` folder as a ZIP archive
+- `Download ZIP` always exports the current `~/spaces/<spaceId>/` folder through the authenticated backend `folder_download` endpoint, with a `HEAD` preflight for inline errors and the real ZIP download handed off to the browser as an attachment
 - `Upload ZIP` always validates through the backend import endpoint; if the current space already has meaningful content, the modal asks whether to overwrite that current space or keep it and import as a new `imported-N` space
 - imported destinations ignore the incoming archive id or title for naming; non-overwrite imports are always installed as `imported-1`, `imported-2`, and so on
-- when `CLOUD_SHARE_URL` resolves to a base URL, the same native spaces dialog shows the hosted-share panel first, uploads the current space ZIP to that receiver, returns the share link in an inline copy field, and keeps any hosted-share errors inside that panel while logging the underlying exception to the console
+- when `CLOUD_SHARE_URL` resolves to a base URL, the same native spaces dialog shows the hosted-share panel first, fetches the current space ZIP from the authenticated backend `folder_download` endpoint, uploads it to that receiver, returns the share link in an inline copy field, and keeps any hosted-share errors inside that panel while logging the underlying exception to the console
 - the hosted-share branch can optionally encrypt the ZIP in the browser with a password before upload, using the same public `share-crypto` helper as the public share-open page
 - local ZIP export and import stay available even when hosted sharing is disabled or the remote receiver rejects uploads
 

app/L0/_all/mod/_core/documentation/docs/server/api/files.md

@@ -130,7 +130,7 @@ It is the right tool for catalog discovery, not for raw filesystem walking.
 - supports `HEAD` for permission-only validation
 - supports `GET` and `POST` for the actual ZIP download
 - resolves readable folders through the shared permission model
-- creates the archive in `server/tmp/`
+- creates the archive in `server/tmp/` with the backend Node ZIP helper instead of a host `zip` binary
 - streams the attachment instead of buffering the ZIP into browser memory
 
 Frontend code that wants an attachment-style download should prefer:

app/L0/_all/mod/_core/documentation/docs/server/request-flow-and-pages.md

@@ -113,6 +113,12 @@ The router supports direct authenticated fetches for app files:
 
 These paths stay logical even when writable storage is relocated through `CUSTOMWARE_PATH`.
 
+Path handling and delivery details:
+
+- direct app-file fetches percent-decode each URL path segment before logical path normalization, so normal browser-encoded filenames such as spaces, brackets, unicode, `#`, and `?` resolve to the actual on-disk file name
+- encoded separators such as `%2F` and `%5C` are rejected instead of being allowed to become filesystem path separators during later normalization
+- direct app-file fetches, page assets, and module files are streamed from disk after a stat check instead of being fully buffered into server RAM before the response starts
+
 ## Cross-Worker Visibility
 
 Clustered writes are ordered through the primary watchdog owner and the shared state version.

app/L0/_all/mod/_core/spaces/AGENTS.md

@@ -57,7 +57,8 @@ Current files and folders:
 - `scripts/`: current-space shared JavaScript modules loaded from widget renderers through `ctx.import("scripts/...")`
 - the routed header share button should always open the spaces-owned share modal, even when hosted cloud sharing is disabled, because local ZIP export and import are always available
 - ZIP import should accept raw space archives exported from a space root, prompt before replacing a non-empty current space, and otherwise install the incoming archive as a new `imported-N` space without trusting the archive title or folder id for the destination name
-- hosted cloud sharing is optional UI inside that same modal: when `CLOUD_SHARE_URL` resolves to a non-empty base URL, or falls back to the schema default `share.space-agent.ai`, the modal may upload the current space ZIP there, optionally encrypting the ZIP in the browser with `server/pages/res/share-crypto.js` before upload; the modal should treat hosted sharing as additive and must not block local ZIP export or import when the hosted receiver is unavailable
+- hosted cloud sharing is optional UI inside that same modal: when `CLOUD_SHARE_URL` resolves to a non-empty base URL, or falls back to the schema default `share.space-agent.ai`, the modal may fetch the current space ZIP from the authenticated backend `folder_download` endpoint, optionally encrypt it in the browser with `server/pages/res/share-crypto.js`, and upload it to the hosted receiver; hosted sharing is additive and must not block local ZIP export or import when the hosted receiver is unavailable
+- local `Download ZIP` from the spaces share modal should use the authenticated backend `folder_download` attachment path, preflight it with `HEAD` for user-visible errors, and let the browser download the streamed ZIP without buffering it into a browser blob first
 - `thumbnail.webp` or `thumbnail.jpg`: optional experimental dashboard-card background image captured from the currently open routed space; keep the capture logic browser-owned, target a square roughly `200x200` image, bias the crop toward the visible widget bounds instead of empty canvas area, prefer `thumbnail.webp`, remove stale thumbnail files when a space no longer has visible widget content to capture, and trigger thumbnail refresh from the shared current-space post-save reload path rather than from special onboarding-only callsites
 - new spaces are created empty; do not seed starter widgets into fresh manifests or widget folders
 - the first-login onboarding space should stay copy-driven and easy to edit: `_core/spaces/onboarding/first-login-onboarding.js` should install `_core/spaces/onboarding/onboarding_space/` only when the user has no spaces yet, and on the main `/` shell it should rewrite the initial route to that copied space before the router defaults to `#/dashboard`

app/L0/_all/mod/_core/spaces/space-share-modal.js

@@ -188,22 +188,55 @@ async function shouldPromptForOverwrite(spaceId, currentSpace) {
   }
 }
 
-async function fetchSpaceArchiveBytes(spaceId) {
+function buildSpaceDownloadPath(spaceId) {
+  return buildSpaceRootPath(spaceId);
+}
+
+function createSpaceDownloadUrl(spaceId) {
   const runtime = getRuntime();
-  const response = await fetch(runtime.api.folderDownloadUrl(buildSpaceRootPath(spaceId)), {
-    method: "GET",
+  return runtime.api.folderDownloadUrl(buildSpaceDownloadPath(spaceId));
+}
+
+async function readResponseErrorMessage(response, fallback) {
+  let payload = null;
+
+  try {
+    payload = await response.clone().json();
+  } catch {}
+
+  if (payload && typeof payload === "object" && String(payload.error || "").trim()) {
+    return String(payload.error).trim();
+  }
+
+  try {
+    const text = String(await response.text()).trim();
+
+    if (text) {
+      return text;
+    }
+  } catch {}
+
+  return fallback;
+}
+
+async function verifySpaceArchiveDownload(spaceId) {
+  const runtime = getRuntime();
+
+  await runtime.api.call("folder_download", {
+    method: "HEAD",
+    query: {
+      path: buildSpaceDownloadPath(spaceId)
+    }
+  });
+}
+
+async function fetchSpaceArchiveBytes(spaceId) {
+  const response = await fetch(createSpaceDownloadUrl(spaceId), {
     credentials: "same-origin"
   });
 
   if (!response.ok) {
-    let detail = "Unable to create the space ZIP.";
-
-    try {
-      const payload = await response.json();
-      detail = String(payload?.error || detail);
-    } catch {}
-
-    throw new Error(detail);
+    throw new Error(await readResponseErrorMessage(response, "Unable to create the ZIP."));
   }
 
   return new Uint8Array(await response.arrayBuffer());
@@ -422,16 +455,9 @@ const model = {
     this.archiveStatusText = "Preparing ZIP download...";
 
     try {
-      const runtime = getRuntime();
-      const spaceRoot = buildSpaceRootPath(this.spaceId);
-      await runtime.api.call("folder_download", {
-        method: "HEAD",
-        query: {
-          path: spaceRoot
-        }
-      });
+      await verifySpaceArchiveDownload(this.spaceId);
       createAnchorDownload(
-        runtime.api.folderDownloadUrl(spaceRoot),
+        createSpaceDownloadUrl(this.spaceId),
         createDownloadFilename(this.spaceId, this.spaceTitle)
       );
       this.archiveStatusText = "ZIP download started.";
@@ -620,4 +646,3 @@ export async function openSpaceShareModal(options = {}) {
 
 runtime.spaces = runtime.spaces || {};
 runtime.spaces.openShareModal = openSpaceShareModal;
-

app/share/spaces/7GEKj7px.json

@@ -0,0 +1,8 @@
+{
+  "createdAt": "2026-04-21T06:58:56.778Z",
+  "encrypted": false,
+  "encryption": null,
+  "lastUsedAt": "2026-04-21T06:59:16.586Z",
+  "sizeBytes": 20461,
+  "token": "7GEKj7px"
+}