partforge 0.103.0 → 0.104.0

package/docs/AUTHORING-PARTS.md

@@ -2057,8 +2057,17 @@ see "Wiring a part into a runnable app", above, for its full signature):
 **The `allow` list, and what bypasses it.** All three controls take the same
 `allow` list already documented for `"font"` in the control-types table above
 (`"https"` — the default; `"gstatic"`, font-only, `https://fonts.gstatic.com`
-exactly; `"asset"`, a `pfc-asset://` token the host has stored for this part),
-gating what a **param-supplied** value may be. It never restricts a source an
+exactly; `"asset"`, a `pfc-asset://` token the host has stored for this part;
+`"tree"`, vector-only, a `pfc-tree://` token naming artwork that lives as a
+**file inside the part itself** rather than in host storage), gating what a
+**param-supplied** value may be.
+
+`"tree"` is vector-only by construction, not by omission: a part's files are
+text, so a `partforge-vector` JSON document can live in one and a PNG or a
+font cannot. Its payoff is that the artwork is versioned *with* the part —
+a host that stores parts as a file tree keeps the document in the same
+snapshot as the code that reads it, so publishing, history and undo carry the
+two together instead of leaving a param pointing at storage that moved on. It never restricts a source an
 author writes into `images`/`fonts`/`vectors` themselves — that's code, not
 user input.
 
@@ -2338,14 +2347,17 @@ yourself (e.g. to download from a different origin) instead of partforge's own D
   where `ImageAsset` is `{ id, label, url, width, height, thumbUrl }`. With no
   provider a `type: "image"` control degrades to a URL field.
 
-- `onAssetUpload(blob, { kind, filename }) → Promise<string>` — the drop target
-  shared by `"image"`/`"vector"`/`"font"` controls (see "Getting files into a
-  part", below) calls this with the converted artifact after a drop, paste, or
-  file-picker choice, and writes whatever it resolves to into the param.
-  `blob` is the CONVERTED artifact — a PNG, a partforge-vector JSON blob, or the
-  original file for a font — never the user's raw drop; `kind` is `"image"`,
-  `"vector"`, or `"font"`. Must resolve to a non-empty source string (an
-  `https:` URL or a host-defined `pfc-asset:` token); anything else is treated
+- `onAssetUpload(blob, { kind, key, filename }) → Promise<string>` — the drop
+  target shared by `"image"`/`"vector"`/`"font"` controls (see "Getting files
+  into a part", below) calls this with the converted artifact after a drop,
+  paste, or file-picker choice, and writes whatever it resolves to into the
+  param. `blob` is the CONVERTED artifact — a PNG, a partforge-vector JSON blob,
+  or the original file for a font — never the user's raw drop; `kind` is
+  `"image"`, `"vector"`, or `"font"`; `key` is the param the drop landed on,
+  which is what lets a host give each control a stable destination of its own
+  rather than reconciling uploads against the part afterwards. Must resolve to
+  a non-empty source string (an `https:` URL, or a host-defined `pfc-asset:` or
+  `pfc-tree:` token); anything else is treated
   as a contract violation and reported through the control's own error line,
   not written into the param. Omit it and the converted bytes land straight in
   the param instead — the path a host that cannot fetch URLs (the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.103.0",
+  "version": "0.104.0",
   "description": "Turn a declarative part definition into a parametric-CAD web app (three.js + Manifold/Replicad). Requires a Vite-based consumer.",
   "type": "module",
   "license": "MIT",

package/src/framework/panel/widgets/file-drop.js

@@ -96,7 +96,7 @@ function el(tag, className, text) {
 // The click path is dropped rather than hidden, deliberately: an invisible
 // overlay that still swallowed clicks would eat the button underneath it, which
 // is the one affordance ambient mode exists to protect.
-export function makeFileDrop({ kind, onSource, onError, onAssetUpload, ambient = false }) {
+export function makeFileDrop({ kind, key, onSource, onError, onAssetUpload, ambient = false }) {
   const row = rowFor(kind);
   const wrap = el("div", ambient ? "file-drop file-drop-ambient" : "file-drop");
   if (!ambient) {
@@ -219,7 +219,14 @@ export function makeFileDrop({ kind, onSource, onError, onAssetUpload, ambient =
 
     if (onAssetUpload) {
       try {
-        const source = await onAssetUpload(artifact.blob, { kind, filename: file.name });
+        // `key` is the PARAM the drop landed on. A host needs it to give a
+        // control a stable destination of its own — partforge-cloud derives
+        // one file path per key, so re-dropping replaces that control's
+        // artwork in place instead of accumulating files it must later
+        // reconcile against the part. Purely informational to partforge:
+        // the hook still answers with a source string and nothing here
+        // reads the key back.
+        const source = await onAssetUpload(artifact.blob, { kind, key, filename: file.name });
         if (stale()) return;
         // A host hook that resolves to anything but a non-empty string —
         // `undefined`, an object, `""` — is a contract violation, not a
@@ -329,6 +336,7 @@ export function mountDrop(kind, { params, node, onAssetUpload, onChange, onCommi
 
   const drop = makeFileDrop({
     kind,
+    key: node.key,
     ambient,
     onAssetUpload,
     onSource: (source) => {

package/src/framework/vector-source.js

@@ -52,6 +52,14 @@ import { unwrapModule } from "./asset-resolve.js";
 export const VECTOR_ALLOW_DEFAULT = ["https"];
 
 const ASSET_SCHEME = "pfc-asset:";
+// Artwork that lives as a FILE IN THE PART ITSELF, addressed by its path
+// rather than by a host-side storage id. Vector-only, and the asymmetry is
+// structural rather than an omission: a part's files are text, so a JSON
+// document can live in one and a PNG cannot. A host that stores parts as a
+// file tree (partforge-cloud is the motivating case) resolves this scheme
+// against that tree; partforge itself only decides whether a param may carry
+// it, exactly as it does for `pfc-asset:`.
+const TREE_SCHEME = "pfc-tree:";
 
 // The "unset" vector source. An empty value declares NO artwork for that
 // name — mirrors isNoFontSource/isNoImageSource exactly. Never a source to
@@ -94,6 +102,7 @@ export function vectorSourceAllowed(source, allow = VECTOR_ALLOW_DEFAULT) {
     // "pfc-asset://" must not pass, and neither must a lookalike host.
     if (kind === "https" && u.protocol === "https:") return true;
     if (kind === "asset" && u.protocol === ASSET_SCHEME) return true;
+    if (kind === "tree" && u.protocol === TREE_SCHEME) return true;
   }
   return false;
 }