@field/cascade 0.12.0 → 0.13.0

package/AGENTS.md

@@ -138,7 +138,7 @@ Definition rules:
 - Vector props support `min`, `max`, and `step`, shared across components. Props may declare a default `expression`; an explicitly saved value overrides that default, including when it equals the numeric default.
 - WebGPU nodes declare `gpu` and use its shared device and per-node `cache`. Portable GPU nodes can run through optional Dawn in the CLI; browser-only declarations remain refused. Import constants and explicit `readTexture` (RGBA8 only) from `cascade/gpu`. Graph texture exchange remains future work. See `doc/HEADLESS_GPU.md` for bounded agent renders, diagnostics and hardware tests.
 - Treat graph wires as the primary data boundary. A node may observe only its connected inputs, its props, and declared host capabilities; it must not inspect sibling nodes or the graph to discover data.
-- Deterministic node modules may not retain module-level mutable values, access ambient state such as `globalThis`, browser storage, or `process`, run top-level effects, or import sibling node implementations. `cascade check` reports these as `architecture/*` diagnostics.
+- Deterministic node modules may not retain module-level mutable values, access ambient state such as `globalThis`, browser storage, or `process`, run top-level effects, or import sibling node implementations. `cascade check` reports these as `architecture/*` diagnostics. Pure module-level helpers are allowed: function declarations, and `const` values that cannot change (literals and arithmetic, `Math.PI`, arrow functions, arrays and objects under `as const` or `Object.freeze`). `let`, `new Map()`, a bare `[]`/`{}`, a regex or any other call is module state.
 - A cache may memoize computation from wired inputs, but it must never supply unwired data. Make cache use an explicitly labelled prop and keep cache keys derived from the complete wired input and relevant props.
 - Keep model/provider integrations in the project. Cascade core has no Google,
   Anthropic, OpenAI, or generic `ai` capability. Use normal typed outputs such

package/CHANGELOG.md

@@ -4,6 +4,56 @@ Notable changes to Cascade. Newest first.
 
 ## Unreleased
 
+## 0.13.0 — 2026-11-09
+
+### Added
+
+- **Browser player without chrome.** `mount(…, { chrome: false })`, or
+  `player.html?chrome=0` in a plain iframe, shows the output alone on a
+  transparent page: no dark frame, Play button or frame field. See
+  `doc/WEB_PLAYER.md`.
+- **Read-only roots outside the project.** `"reads": ["../other/data"]` in
+  `cascade.json` lets file reads (`files`, `cascade/io`, Studio media) resolve
+  into another folder by `..` or a symlink; writes there are still refused,
+  and any other path out of the project still is. See "Reading another
+  project's data" in `doc/PROJECT_AUTHORING.md`.
+- **Named exports and a keyed cache for nodes.** `"writes": ["renders"]` in
+  `cascade.json` lets the `files` capability write stably named files into a
+  declared project folder beside `.cascade-cache/`. `files.cache.get(key)` /
+  `files.cache.put(key, data)` (contract `KeyedCache`) keep entries under
+  `.cascade-cache/keyed/<key>`, found again by key on the next run, where
+  `cascade/io` names carry a content hash. `files.write` is now atomic, and
+  normalises before its folder test, so `.cascade-cache/../x` is refused.
+- **Node files may hold immutable module-level constants.** Helper functions
+  were already allowed; `architecture/module-state` now also passes `const`s
+  that cannot change (`const TAU = Math.PI * 2`, `[...] as const`,
+  `Object.freeze({...})`, arrow-function helpers). `let`, `new Map()`, a bare
+  array or object, a regex and other calls are still refused.
+
+### Fixed
+
+- **The browser player re-cooks only what changed.** `setProp`, `setInput`
+  and each frame now cook the changed node and what lies downstream of it;
+  an unchanged upstream node keeps its outputs (`reuse: "strict"`), so a
+  paint prop no longer re-runs a slow data node above it.
+- **`cascade render --workers` accepts a piece animated on twos.** Two frames
+  whose node saved the same drawing land on one content-named cache file
+  (`.cascade-cache/<node>.<hash>.png`); that is the same bytes, not a
+  clobber, so the fixed-path probe no longer refuses it.
+
+### Changed
+
+- **`FileCapability` has a required `cache: KeyedCache` member.** A custom
+  host that implements the `files` capability itself must now provide
+  `cache.get(key)` and `cache.put(key, data)`; it no longer type-checks
+  without them. Studio and the headless host already do.
+
+### Known gaps
+
+- **Ramp's stop editor and Image's file picker are not in Studio yet.** The
+  definition-v1 port of the image nodes left them out. Graphs that already
+  set them render unchanged.
+
 ## 0.12.0 — 2026-11-09
 
 ### Added

package/README.md

@@ -36,7 +36,7 @@ cascade .                          # reopen it later
 cascade run index.cascade --frames 1 --json   # render headlessly
 ```
 
-The npm package is at 0.12.0 and includes every command below. 0.12 adds `cascade share`, `ladder --cairn`, scrub number fields and the full GPU limits; see the [changelog](CHANGELOG.md).
+The npm package is at 0.13.0 and includes every command below. 0.13 adds the chrome-free player, read-only roots and named writes in `cascade.json`, a keyed node cache and module-level constants in node files; see the [changelog](CHANGELOG.md).
 
 ## New in 0.9: shareable editors
 

package/dist/cli/{chunk-OM6BEME6.js → chunk-2L34ERS2.js}

@@ -3,14 +3,14 @@ import {
   moduleId,
   projectModuleFile,
   validateNodeModuleArchitecture
-} from "./chunk-MP653A5O.js";
+} from "./chunk-QKL7CCRS.js";
 import {
   builtinNodeRegistration
 } from "./chunk-MI5JLQYA.js";
 import {
   ProjectRoot,
   extractNodeDefinition
-} from "./chunk-2JEU3MGB.js";
+} from "./chunk-W5PJ5RMP.js";
 
 // src/cli/webBuild.ts
 import fs from "node:fs/promises";
@@ -264,4 +264,4 @@ export {
   inside,
   exists
 };
-//# sourceMappingURL=chunk-OM6BEME6.js.map
+//# sourceMappingURL=chunk-2L34ERS2.js.map

package/dist/cli/{chunk-3RXL5GHB.js → chunk-JEW5MPGI.js}

@@ -5,21 +5,21 @@ import {
   inside,
   playerFile,
   staticRuntimePlugin
-} from "./chunk-OM6BEME6.js";
+} from "./chunk-2L34ERS2.js";
 import {
   PREFLIGHT_WARNING_CODES,
   createRuntime,
   moduleId,
   projectModuleFile,
   validateNodeModuleArchitecture
-} from "./chunk-MP653A5O.js";
+} from "./chunk-QKL7CCRS.js";
 import {
   builtinNodeRegistration
 } from "./chunk-MI5JLQYA.js";
 import {
   ProjectRoot,
   extractNodeDefinition
-} from "./chunk-2JEU3MGB.js";
+} from "./chunk-W5PJ5RMP.js";
 
 // packages/runtime/src/editor/index.ts
 var SCENE_FORMAT = "cascade.scene";
@@ -813,4 +813,4 @@ export {
   scanForLeaks,
   deployVercel
 };
-//# sourceMappingURL=chunk-3RXL5GHB.js.map
+//# sourceMappingURL=chunk-JEW5MPGI.js.map

package/dist/cli/{chunk-ST6LROUG.js → chunk-OBZAP3GG.js}

@@ -27,7 +27,7 @@ import {
   runDeterministicProjectGraph,
   saveStillImages,
   validateProjectGraph
-} from "./chunk-MP653A5O.js";
+} from "./chunk-QKL7CCRS.js";
 import {
   graphSeed
 } from "./chunk-L6B6FUQP.js";
@@ -37,14 +37,14 @@ import {
 import {
   compileEmbedded,
   compileProjectModule
-} from "./chunk-EU4ZFZ7Y.js";
+} from "./chunk-W7OUAT7J.js";
 import {
   cascadeVersion,
   formatStageTrace
 } from "./chunk-5ORUQ6ES.js";
 import {
   ProjectRoot
-} from "./chunk-2JEU3MGB.js";
+} from "./chunk-W5PJ5RMP.js";
 
 // src/cli/runner.ts
 import * as fs from "fs/promises";
@@ -264,4 +264,4 @@ export {
   renderSuggestion,
   runGraph
 };
-//# sourceMappingURL=chunk-ST6LROUG.js.map
+//# sourceMappingURL=chunk-OBZAP3GG.js.map

package/dist/cli/{chunk-73S4JZXK.js → chunk-QAGATJGE.js}

@@ -7,14 +7,14 @@ import {
   formatPlan,
   fromBase64,
   parseScene
-} from "./chunk-3RXL5GHB.js";
+} from "./chunk-JEW5MPGI.js";
 import {
   cookProjectGraph,
   installProjectIo
-} from "./chunk-MP653A5O.js";
+} from "./chunk-QKL7CCRS.js";
 import {
   ProjectRoot
-} from "./chunk-2JEU3MGB.js";
+} from "./chunk-W5PJ5RMP.js";
 
 // src/cli/editorCommands.ts
 import fs from "node:fs/promises";
@@ -34,7 +34,7 @@ Shareable editors (see doc/EDITOR_EXPORT.md):
 async function runEditorCommand(args) {
   const [command, graph] = args;
   if (command === "share") {
-    const { runShareCommand } = await import("./share-MHF6TNRK.js");
+    const { runShareCommand } = await import("./share-B7HTCOJX.js");
     return runShareCommand(args);
   }
   if (!graph || graph.startsWith("-")) throw new Error(`cascade ${command} requires a graph file`);
@@ -333,4 +333,4 @@ export {
   runEditorCommand,
   sceneDocument
 };
-//# sourceMappingURL=chunk-73S4JZXK.js.map
+//# sourceMappingURL=chunk-QAGATJGE.js.map

package/dist/cli/{chunk-MP653A5O.js → chunk-QKL7CCRS.js}

@@ -62,7 +62,7 @@ import {
 import {
   ProjectRoot,
   extractNodeDefinition
-} from "./chunk-2JEU3MGB.js";
+} from "./chunk-W5PJ5RMP.js";
 import {
   CAPABILITIES_BY_ENVIRONMENT,
   validateNodeDefinition
@@ -2237,6 +2237,9 @@ function validateNodeModuleArchitecture(source, fileName, ts2) {
     (statement) => ts2.isVariableStatement(statement) && isDefinition(statement)
   );
   for (const statement of file.statements) {
+    if (ts2.isVariableStatement(statement) && !isDefinition(statement) && !supersededByDefinition(statement) && isPureConstant(statement)) {
+      continue;
+    }
     if (ts2.isVariableStatement(statement) && !isDefinition(statement)) {
       const superseded = supersededByDefinition(statement);
       add(
@@ -2301,6 +2304,48 @@ function validateNodeModuleArchitecture(source, fileName, ts2) {
     if (!declaration || !ts2.isIdentifier(declaration.name)) return null;
     return declaration.name.text === "icon" || declaration.name.text === "runsOn" ? declaration.name.text : null;
   }
+  function isPureConstant(statement) {
+    if (!(statement.declarationList.flags & ts2.NodeFlags.Const)) return false;
+    return statement.declarationList.declarations.every(
+      (declaration) => ts2.isIdentifier(declaration.name) && declaration.initializer !== void 0 && isPure(declaration.initializer, false)
+    );
+  }
+  function isPure(node, frozen) {
+    if (ts2.isNumericLiteral(node) || ts2.isStringLiteral(node) || ts2.isBigIntLiteral(node) || ts2.isNoSubstitutionTemplateLiteral(node) || node.kind === ts2.SyntaxKind.TrueKeyword || node.kind === ts2.SyntaxKind.FalseKeyword || node.kind === ts2.SyntaxKind.NullKeyword) return true;
+    if (ts2.isIdentifier(node)) return true;
+    if (ts2.isArrowFunction(node) || ts2.isFunctionExpression(node)) return true;
+    if (ts2.isParenthesizedExpression(node)) return isPure(node.expression, frozen);
+    if (ts2.isAsExpression(node))
+      return isPure(node.expression, frozen || isConstAssertion(node.type));
+    if (ts2.isSatisfiesExpression(node) || ts2.isNonNullExpression(node) || ts2.isTypeAssertionExpression(node))
+      return isPure(node.expression, frozen);
+    if (ts2.isPrefixUnaryExpression(node))
+      return node.operator !== ts2.SyntaxKind.PlusPlusToken && node.operator !== ts2.SyntaxKind.MinusMinusToken && isPure(node.operand, false);
+    if (ts2.isBinaryExpression(node))
+      return !isAssignment(node.operatorToken.kind) && isPure(node.left, false) && isPure(node.right, false);
+    if (ts2.isConditionalExpression(node))
+      return isPure(node.condition, false) && isPure(node.whenTrue, frozen) && isPure(node.whenFalse, frozen);
+    if (ts2.isTemplateExpression(node))
+      return node.templateSpans.every((span) => isPure(span.expression, false));
+    if (ts2.isPropertyAccessExpression(node)) return isPure(node.expression, false);
+    if (ts2.isElementAccessExpression(node))
+      return isPure(node.expression, false) && isPure(node.argumentExpression, false);
+    if (ts2.isArrayLiteralExpression(node))
+      return frozen && node.elements.every((element) => !ts2.isSpreadElement(element) && isPure(element, true));
+    if (ts2.isObjectLiteralExpression(node))
+      return frozen && node.properties.every((property) => ts2.isPropertyAssignment(property) ? !ts2.isComputedPropertyName(property.name) && isPure(property.initializer, true) : ts2.isShorthandPropertyAssignment(property));
+    if (ts2.isCallExpression(node) && ts2.isPropertyAccessExpression(node.expression) && ts2.isIdentifier(node.expression.expression) && node.expression.expression.text === "Object" && node.expression.name.text === "freeze" && node.arguments.length === 1) {
+      const [argument] = node.arguments;
+      return ts2.isArrayLiteralExpression(argument) ? argument.elements.every((element) => !ts2.isSpreadElement(element) && isPure(element, false)) : ts2.isObjectLiteralExpression(argument) ? argument.properties.every((property) => ts2.isPropertyAssignment(property) && !ts2.isComputedPropertyName(property.name) && isPure(property.initializer, false)) : false;
+    }
+    return false;
+  }
+  function isConstAssertion(type) {
+    return ts2.isTypeReferenceNode(type) && ts2.isIdentifier(type.typeName) && type.typeName.text === "const";
+  }
+  function isAssignment(kind) {
+    return kind >= ts2.SyntaxKind.FirstAssignment && kind <= ts2.SyntaxKind.LastAssignment;
+  }
   function isDefinition(statement) {
     return Boolean(statement.declarationList.flags & ts2.NodeFlags.Const) && Boolean(statement.modifiers?.some((item) => item.kind === ts2.SyntaxKind.ExportKeyword)) && statement.declarationList.declarations.length === 1 && ts2.isIdentifier(statement.declarationList.declarations[0].name) && statement.declarationList.declarations[0].name.text === "definition";
   }
@@ -2337,25 +2382,41 @@ function normalize(value) {
 }
 
 // src/cli/nodeFiles.ts
+import { randomBytes } from "node:crypto";
 import fs from "node:fs/promises";
 import path from "node:path";
+var KEYED_DIR = ".cascade-cache/keyed";
+var KEY = /^[A-Za-z0-9][A-Za-z0-9._-]*(?:\/[A-Za-z0-9][A-Za-z0-9._-]*)*$/;
 function createNodeFileCapability(project) {
   const within2 = (relative, what) => {
     try {
-      return project.resolve(relative.replace(/^\.?\//, ""));
+      const clean = relative.replace(/^\.?\//, "");
+      return what === "writing" ? project.resolve(clean) : project.resolveMedia(clean);
     } catch (error) {
       throw new Error(
         `files: ${what} outside the project is refused \u2014 ${relative} (${error instanceof Error ? error.message : String(error)})`
       );
     }
   };
-  const cacheOnly = (relative) => {
+  const writable = (relative) => {
     const clean = relative.replace(/^\.?\//, "");
-    if (!clean.startsWith(".cascade-cache/"))
+    const full = within2(clean, "writing");
+    if (!project.writeFolderOf(clean))
       throw new Error(
-        `files: writes are confined to .cascade-cache/ \u2014 got ${clean}. A node's output is derived data, and the same rule applies in the browser.`
+        `files: writes are confined to .cascade-cache/ and the folders cascade.json "writes" declares \u2014 got ${clean}. A node's output is derived data; declare an export folder such as "writes": ["renders"] to write named files.`
       );
-    return within2(clean, "writing");
+    return full;
+  };
+  const writeWhole2 = async (full, data) => {
+    await fs.mkdir(path.dirname(full), { recursive: true });
+    const staging = `${full}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`;
+    await fs.writeFile(staging, data);
+    await fs.rename(staging, full);
+  };
+  const keyed = (key) => {
+    if (typeof key !== "string" || key.length > 512 || !KEY.test(key))
+      throw new Error(`files.cache: key ${JSON.stringify(key)} must be letters, digits, ".", "_" and "-" in "/"-separated parts, each starting with a letter or digit`);
+    return within2(`${KEYED_DIR}/${key}`, "writing");
   };
   const live = (options) => {
     if (options.signal.aborted) throw new Error("files: cancelled");
@@ -2367,9 +2428,22 @@ function createNodeFileCapability(project) {
     },
     async write(relative, data, options) {
       live(options);
-      const full = cacheOnly(relative);
-      await fs.mkdir(path.dirname(full), { recursive: true });
-      await fs.writeFile(full, data);
+      await writeWhole2(writable(relative), data);
+    },
+    cache: {
+      async get(key, options) {
+        live(options);
+        try {
+          return new Uint8Array(await fs.readFile(keyed(key)));
+        } catch (error) {
+          if (error.code === "ENOENT") return null;
+          throw error;
+        }
+      },
+      async put(key, data, options) {
+        live(options);
+        await writeWhole2(keyed(key), data);
+      }
     },
     async list(relative, options) {
       live(options);
@@ -3763,4 +3837,4 @@ export {
   builtinModuleIds,
   diagnoseGraph
 };
-//# sourceMappingURL=chunk-MP653A5O.js.map
+//# sourceMappingURL=chunk-QKL7CCRS.js.map

package/dist/cli/{chunk-2JEU3MGB.js → chunk-W5PJ5RMP.js}

@@ -39,6 +39,19 @@ function resolveWithinRoot(root, ...segments) {
   }
   return full;
 }
+function canonicalPath(full) {
+  let existing = full;
+  while (!existsIncludingSymlink(existing)) {
+    const parent = path.dirname(existing);
+    if (parent === existing) return full;
+    existing = parent;
+  }
+  return path.join(canonical(existing, `path is not accessible: ${full}`), path.relative(existing, full));
+}
+function isWithin(base, candidate) {
+  const rel = path.relative(base, candidate);
+  return !rel.startsWith("..") && !path.isAbsolute(rel);
+}
 function existsIncludingSymlink(candidate) {
   try {
     fs.lstatSync(candidate);
@@ -56,6 +69,101 @@ function canonical(candidate, message) {
   }
 }
 
+// server/src/projectConfig.ts
+import fs2 from "node:fs";
+import path2 from "node:path";
+var CREDENTIAL_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+var SECRET_KEY = /^(?:api[_-]?key|apiKey|secret|password|access[_-]?token|refresh[_-]?token|credential|credentials)$/i;
+function readProjectManifest(root) {
+  const raw = readRaw(root);
+  return normalizeManifest(raw);
+}
+function writeProjectManifest(root, input) {
+  if (!input || typeof input !== "object" || Array.isArray(input)) throw new Error("project manifest must be an object");
+  const value = input;
+  const current = readRaw(root);
+  const next = {
+    ...current,
+    name: typeof value.name === "string" ? value.name.trim() : "",
+    commands: stringRecord(value.commands, "commands"),
+    credentials: credentialNames(value.credentials),
+    settings: settingsRecord(value.settings)
+  };
+  fs2.writeFileSync(path2.join(root, "cascade.json"), `${JSON.stringify(next, null, 2)}
+`, "utf8");
+  return normalizeManifest(next);
+}
+function readRaw(root) {
+  try {
+    const value = JSON.parse(fs2.readFileSync(path2.join(root, "cascade.json"), "utf8"));
+    if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("root must be an object");
+    return value;
+  } catch (error) {
+    if (error.code === "ENOENT") return {};
+    throw new Error(`Cannot read cascade.json: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+function normalizeManifest(raw) {
+  return Object.freeze({
+    name: typeof raw.name === "string" ? raw.name : "",
+    commands: Object.freeze(stringRecord(raw.commands, "commands")),
+    credentials: Object.freeze(credentialNames(raw.credentials)),
+    settings: Object.freeze(settingsRecord(raw.settings)),
+    reads: Object.freeze(relativeFolders(raw.reads, "reads", true)),
+    writes: Object.freeze(relativeFolders(raw.writes, "writes", false))
+  });
+}
+function relativeFolders(input, label, mayLeave) {
+  if (input === void 0) return [];
+  const shape = mayLeave ? '"../other/data"' : '"renders"';
+  if (!Array.isArray(input)) throw new Error(`cascade.json ${label} must be an array of relative folders such as [${shape}]`);
+  const folders = input.map((entry) => {
+    if (typeof entry !== "string" || !entry.trim() || entry.includes("\0") || path2.isAbsolute(entry) || /^~/.test(entry))
+      throw new Error(`cascade.json ${label}: ${JSON.stringify(entry)} is not a relative folder such as ${shape}`);
+    const folder = path2.posix.normalize(entry.split("\\").join("/")).replace(/\/+$/, "");
+    const leaves = folder === ".." || folder.startsWith("../");
+    if (!mayLeave && (leaves || folder === "." || /^(?:\.git|nodes|\.cascade)(?:\/|$)/.test(folder)))
+      throw new Error(`cascade.json writes: ${JSON.stringify(entry)} must be a folder inside the project, not its root, .git, .cascade or nodes`);
+    if (mayLeave && folder === ".") throw new Error('cascade.json reads: "." is the project itself, which is always readable');
+    return folder;
+  });
+  return [...new Set(folders)];
+}
+function stringRecord(input, label) {
+  if (input === void 0) return {};
+  if (!input || typeof input !== "object" || Array.isArray(input)) throw new Error(`${label} must be an object of strings`);
+  const entries = Object.entries(input);
+  if (entries.some(([key, value]) => !CREDENTIAL_NAME.test(key) || typeof value !== "string" || value.includes("\0"))) {
+    throw new Error(`${label} must contain safe names and string values`);
+  }
+  return Object.fromEntries(entries);
+}
+function credentialNames(input) {
+  if (input === void 0) return [];
+  if (!Array.isArray(input) || input.some((name) => typeof name !== "string" || !CREDENTIAL_NAME.test(name))) {
+    throw new Error("credentials must be an array of safe names");
+  }
+  return [...new Set(input)];
+}
+function settingsRecord(input) {
+  if (input === void 0) return {};
+  if (!input || typeof input !== "object" || Array.isArray(input)) throw new Error("settings must be an object");
+  assertSafeSettings(input, 0);
+  return structuredClone(input);
+}
+function assertSafeSettings(value, depth) {
+  if (depth > 12) throw new Error("settings nesting is too deep");
+  if (value === null || typeof value === "string" || typeof value === "boolean" || typeof value === "number" && Number.isFinite(value)) return;
+  if (Array.isArray(value)) return value.forEach((item) => assertSafeSettings(item, depth + 1));
+  if (!value || typeof value !== "object") throw new Error("settings must contain JSON values");
+  for (const [key, item] of Object.entries(value)) {
+    if (key === "__proto__" || key === "constructor" || key === "prototype" || SECRET_KEY.test(key)) {
+      throw new Error(`settings key ${JSON.stringify(key)} looks secret or unsafe; credentials belong outside the project`);
+    }
+    assertSafeSettings(item, depth + 1);
+  }
+}
+
 // server/src/shell/service.ts
 import fs4 from "node:fs";
 import os2 from "node:os";
@@ -64,11 +172,11 @@ import { execFile, spawn } from "node:child_process";
 import { randomUUID } from "node:crypto";
 
 // server/src/credentials.ts
-import fs2 from "node:fs";
+import fs3 from "node:fs";
 import os from "node:os";
-import path2 from "node:path";
+import path3 from "node:path";
 var CredentialStore = class {
-  constructor(file = process.env.CASCADE_CREDENTIALS || path2.join(os.homedir(), ".cascade", "credentials.yaml")) {
+  constructor(file = process.env.CASCADE_CREDENTIALS || path3.join(os.homedir(), ".cascade", "credentials.yaml")) {
     this.file = file;
   }
   has(name) {
@@ -96,7 +204,7 @@ var CredentialStore = class {
   read() {
     let source;
     try {
-      source = fs2.readFileSync(this.file, "utf8");
+      source = fs3.readFileSync(this.file, "utf8");
     } catch (error) {
       if (error.code === "ENOENT") return /* @__PURE__ */ new Map();
       throw error;
@@ -170,83 +278,6 @@ function safeEnvName(value) {
   return value && /^[A-Za-z_][A-Za-z0-9_]{0,127}$/.test(value) && !/^(?:PATH|NODE_OPTIONS|PYTHONPATH|LD_.*|DYLD_.*)$/i.test(value) ? value : null;
 }
 
-// server/src/projectConfig.ts
-import fs3 from "node:fs";
-import path3 from "node:path";
-var CREDENTIAL_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
-var SECRET_KEY = /^(?:api[_-]?key|apiKey|secret|password|access[_-]?token|refresh[_-]?token|credential|credentials)$/i;
-function readProjectManifest(root) {
-  const raw = readRaw(root);
-  return normalizeManifest(raw);
-}
-function writeProjectManifest(root, input) {
-  if (!input || typeof input !== "object" || Array.isArray(input)) throw new Error("project manifest must be an object");
-  const value = input;
-  const current = readRaw(root);
-  const next = {
-    ...current,
-    name: typeof value.name === "string" ? value.name.trim() : "",
-    commands: stringRecord(value.commands, "commands"),
-    credentials: credentialNames(value.credentials),
-    settings: settingsRecord(value.settings)
-  };
-  fs3.writeFileSync(path3.join(root, "cascade.json"), `${JSON.stringify(next, null, 2)}
-`, "utf8");
-  return normalizeManifest(next);
-}
-function readRaw(root) {
-  try {
-    const value = JSON.parse(fs3.readFileSync(path3.join(root, "cascade.json"), "utf8"));
-    if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("root must be an object");
-    return value;
-  } catch (error) {
-    if (error.code === "ENOENT") return {};
-    throw new Error(`Cannot read cascade.json: ${error instanceof Error ? error.message : String(error)}`);
-  }
-}
-function normalizeManifest(raw) {
-  return Object.freeze({
-    name: typeof raw.name === "string" ? raw.name : "",
-    commands: Object.freeze(stringRecord(raw.commands, "commands")),
-    credentials: Object.freeze(credentialNames(raw.credentials)),
-    settings: Object.freeze(settingsRecord(raw.settings))
-  });
-}
-function stringRecord(input, label) {
-  if (input === void 0) return {};
-  if (!input || typeof input !== "object" || Array.isArray(input)) throw new Error(`${label} must be an object of strings`);
-  const entries = Object.entries(input);
-  if (entries.some(([key, value]) => !CREDENTIAL_NAME.test(key) || typeof value !== "string" || value.includes("\0"))) {
-    throw new Error(`${label} must contain safe names and string values`);
-  }
-  return Object.fromEntries(entries);
-}
-function credentialNames(input) {
-  if (input === void 0) return [];
-  if (!Array.isArray(input) || input.some((name) => typeof name !== "string" || !CREDENTIAL_NAME.test(name))) {
-    throw new Error("credentials must be an array of safe names");
-  }
-  return [...new Set(input)];
-}
-function settingsRecord(input) {
-  if (input === void 0) return {};
-  if (!input || typeof input !== "object" || Array.isArray(input)) throw new Error("settings must be an object");
-  assertSafeSettings(input, 0);
-  return structuredClone(input);
-}
-function assertSafeSettings(value, depth) {
-  if (depth > 12) throw new Error("settings nesting is too deep");
-  if (value === null || typeof value === "string" || typeof value === "boolean" || typeof value === "number" && Number.isFinite(value)) return;
-  if (Array.isArray(value)) return value.forEach((item) => assertSafeSettings(item, depth + 1));
-  if (!value || typeof value !== "object") throw new Error("settings must contain JSON values");
-  for (const [key, item] of Object.entries(value)) {
-    if (key === "__proto__" || key === "constructor" || key === "prototype" || SECRET_KEY.test(key)) {
-      throw new Error(`settings key ${JSON.stringify(key)} looks secret or unsafe; credentials belong outside the project`);
-    }
-    assertSafeSettings(item, depth + 1);
-  }
-}
-
 // server/src/shell/types.ts
 var ShellProcessError = class extends Error {
   constructor(kind, result, message) {
@@ -847,7 +878,48 @@ var ProjectRoot = class _ProjectRoot {
     if (normalized === "shared" || normalized.startsWith("shared/")) {
       return this.resolveShared(...normalized.split("/").slice(1));
     }
-    return this.resolve(relativePath);
+    try {
+      return this.resolve(relativePath);
+    } catch (error) {
+      if (!(error instanceof PathSafetyError)) throw error;
+      const declared = this.resolveDeclaredRead(relativePath);
+      if (declared) return declared;
+      throw error;
+    }
+  }
+  /**
+   * A read outside the project, allowed only into a root the project declares
+   * in cascade.json `"reads"` (`["../other/data"]`). Reached by `..` or by a
+   * symlink alike: the canonical target must lie under the canonical read
+   * root. Never used for writes — `resolve()` still refuses those.
+   */
+  resolveDeclaredRead(relativePath) {
+    if (path5.isAbsolute(relativePath)) return null;
+    const reads = readProjectManifest(this.root).reads;
+    if (!reads.length) return null;
+    const target = canonicalPath(path5.resolve(this.root, relativePath));
+    for (const folder of reads) {
+      let base;
+      try {
+        base = fssync.realpathSync(path5.resolve(this.root, folder));
+      } catch {
+        continue;
+      }
+      if (isWithin(base, target)) return target;
+    }
+    return null;
+  }
+  /**
+   * Where a node may write a file under its own name: `.cascade-cache/`, or a
+   * folder the project declares in cascade.json `"writes"` (`["renders"]`).
+   * Returns the folder the normalised path falls in, or null. Containment is
+   * still `resolve()`'s, so a symlink out of a write folder is refused.
+   */
+  writeFolderOf(relativePath) {
+    const clean = path5.posix.normalize(relativePath.split("\\").join("/").replace(/^\.?\//, ""));
+    for (const folder of [".cascade-cache", ...readProjectManifest(this.root).writes])
+      if (clean.startsWith(`${folder}/`)) return folder;
+    return null;
   }
   /**
    * Whether this project is under version control, walking **up** rather than
@@ -1122,4 +1194,4 @@ export {
   extractNodeDefinition,
   ProjectRoot
 };
-//# sourceMappingURL=chunk-2JEU3MGB.js.map
+//# sourceMappingURL=chunk-W5PJ5RMP.js.map

package/dist/cli/{chunk-EU4ZFZ7Y.js → chunk-W7OUAT7J.js}

@@ -1,6 +1,6 @@
 import {
   readProjectManifest
-} from "./chunk-2JEU3MGB.js";
+} from "./chunk-W5PJ5RMP.js";
 
 // server/src/compile.ts
 import * as esbuild from "esbuild";
@@ -119,4 +119,4 @@ export {
   compileProjectPanel,
   compileEmbedded
 };
-//# sourceMappingURL=chunk-EU4ZFZ7Y.js.map
+//# sourceMappingURL=chunk-W7OUAT7J.js.map

package/dist/cli/{cliCommands-JJN5Z3ZC.js → cliCommands-XVFRD7CF.js}

@@ -5,7 +5,7 @@ import {
   compileEmbedded,
   compileProjectModule,
   compileProjectPanel
-} from "./chunk-EU4ZFZ7Y.js";
+} from "./chunk-W7OUAT7J.js";
 import {
   PythonWorker,
   StageCancelledError,
@@ -34,7 +34,7 @@ import {
   resolveWithinRoot,
   secretValue,
   writeProjectManifest
-} from "./chunk-2JEU3MGB.js";
+} from "./chunk-W5PJ5RMP.js";
 import "./chunk-NJFMDXHR.js";
 import "./chunk-J7VK7MNF.js";
 import "./chunk-FWMSGKEH.js";
@@ -3467,4 +3467,4 @@ export {
   resolveProjectTarget,
   runStudioCli
 };
-//# sourceMappingURL=cliCommands-JJN5Z3ZC.js.map
+//# sourceMappingURL=cliCommands-XVFRD7CF.js.map