@floless/app 0.60.0 → 0.62.0

package/dist/floless-server.cjs

@@ -53022,7 +53022,7 @@ function appVersion() {
   return resolveVersion({
     isSea: isSea2(),
     sqVersionXml: readSqVersionXml(),
-    define: true ? "0.60.0" : void 0,
+    define: true ? "0.62.0" : void 0,
     pkgVersion: readPkgVersion()
   });
 }
@@ -53032,7 +53032,7 @@ function resolveChannel(s) {
   return "dev";
 }
 function appChannel() {
-  return resolveChannel({ isSea: isSea2(), define: true ? "0.60.0" : void 0 });
+  return resolveChannel({ isSea: isSea2(), define: true ? "0.62.0" : void 0 });
 }
 
 // workflow-update.ts
@@ -54017,7 +54017,219 @@ function postProcess(contract, opts = {}) {
     const groups = sheet.groups ? assignIds(sheet.groups, "g") : void 0;
     return { ...sheet, id, elements, layers, ...groups ? { groups } : {} };
   });
-  return { ...contract, type: "drawing.vector/v1", sheets };
+  const datums = contract.datums ? assignIds(contract.datums, "dt") : void 0;
+  const links = contract.links ? assignIds(contract.links, "lk") : void 0;
+  return {
+    ...contract,
+    type: "drawing.vector/v1",
+    sheets,
+    ...datums ? { datums } : {},
+    ...links ? { links } : {}
+  };
+}
+
+// views-to-scene.ts
+function mapper(sheet) {
+  const t = sheet.transform;
+  if (!t || typeof t.scale !== "number" || !(t.scale > 0)) return null;
+  const s = t.scale;
+  const [ox, oy] = t.origin ?? [0, 0];
+  const rot = (t.rotation ?? 0) * Math.PI / 180;
+  const cos = Math.cos(rot);
+  const sin = Math.sin(rot);
+  return (p) => {
+    const dx = p[0] - ox;
+    const dy = p[1] - oy;
+    const rx = dx * cos - dy * sin;
+    const ry = dx * sin + dy * cos;
+    return [rx * s + 0, -ry * s + 0];
+  };
+}
+function uprightHorizontal(sheet) {
+  const dir = sheet.view?.dir ?? "+y";
+  if (dir === "+y") return { axis: "x", sign: 1 };
+  if (dir === "-y") return { axis: "x", sign: -1 };
+  if (dir === "+x") return { axis: "y", sign: -1 };
+  if (dir === "-x") return { axis: "y", sign: 1 };
+  return null;
+}
+function elevationZExtent(sheet, g) {
+  const map = mapper(sheet);
+  if (!map) return null;
+  const pts = collectDisplayPoints(g, sheet);
+  if (pts.length === 0) return null;
+  let lo = Infinity;
+  let hi = -Infinity;
+  for (const p of pts) {
+    const z = map(p)[1];
+    if (z < lo) lo = z;
+    if (z > hi) hi = z;
+  }
+  return lo <= hi ? [lo, hi] : null;
+}
+function worldInterval(sheet, g, component, sign = 1) {
+  const map = mapper(sheet);
+  if (!map) return null;
+  const pts = collectDisplayPoints(g, sheet);
+  if (pts.length === 0) return null;
+  let lo = Infinity;
+  let hi = -Infinity;
+  for (const p of pts) {
+    const v = map(p)[component] * sign;
+    if (v < lo) lo = v;
+    if (v > hi) hi = v;
+  }
+  return lo <= hi ? [lo, hi] : null;
+}
+function collectDisplayPoints(g, sheet) {
+  if (g.footprint && g.footprint.length) return g.footprint;
+  if (g.axis && g.axis.length === 2) return g.axis;
+  const ids = new Set(g.elementIds ?? []);
+  const pts = [];
+  for (const el of sheet.elements ?? []) {
+    if (!el.id || !ids.has(el.id)) continue;
+    if (el.pts) pts.push(...el.pts);
+    else if (el.bbox && el.bbox.length === 4) {
+      pts.push([el.bbox[0], el.bbox[1]], [el.bbox[2], el.bbox[3]]);
+    }
+  }
+  return pts;
+}
+function resolveDatum(v, datums, axis) {
+  if (typeof v === "number") return v;
+  if (typeof v === "string") {
+    const d = datums.find((x) => x.id === v);
+    return d && (d.axis ?? "z") === axis ? d.value : null;
+  }
+  return null;
+}
+var PALETTE = ["#3b82f6", "#f59e0b", "#10b981", "#8b5cf6", "#ef4444", "#14b8a6", "#eab308", "#64748b"];
+function overlapRatio(a, b) {
+  const lo = Math.max(a[0], b[0]);
+  const hi = Math.min(a[1], b[1]);
+  if (hi <= lo) return 0;
+  const shorter = Math.max(1e-9, Math.min(a[1] - a[0], b[1] - b[0]));
+  return (hi - lo) / shorter;
+}
+function viewsToScene(contractInput) {
+  const contract = contractInput ?? {};
+  const sheets = contract.sheets ?? [];
+  const datums = contract.datums ?? [];
+  const links = contract.links ?? [];
+  const elements = [];
+  const skipped = [];
+  const groupKeys = [];
+  const seenKey = /* @__PURE__ */ new Set();
+  const plans = sheets.filter((s) => s.view?.kind === "plan");
+  const uprights = sheets.filter((s) => s.view?.kind === "elevation" || s.view?.kind === "section");
+  const uprightEntities = [];
+  for (const sh of uprights) {
+    const hz = uprightHorizontal(sh);
+    if (!hz) continue;
+    for (const g of sh.groups ?? []) {
+      const z = elevationZExtent(sh, g);
+      const h = worldInterval(sh, g, 0, hz.sign);
+      if (z && h) uprightEntities.push({ sheet: sh, g, z, h, axis: hz.axis });
+    }
+  }
+  const linkedAway = /* @__PURE__ */ new Set();
+  for (const l of links) {
+    if (l.kind !== "same-entity") continue;
+    linkedAway.add(`${l.a.sheet}/${l.a.id ?? ""}`);
+    linkedAway.add(`${l.b.sheet}/${l.b.id ?? ""}`);
+  }
+  function resolveZ(planSheet, g) {
+    if (g.extrude && (g.extrude.from !== void 0 || g.extrude.to !== void 0)) {
+      const exFrom = resolveDatum(g.extrude.from, datums, "z");
+      const exTo = resolveDatum(g.extrude.to, datums, "z");
+      if (exFrom != null && exTo != null) return { z: [exFrom, exTo], how: "extrude" };
+      return { error: "extrude reference unresolved \u2014 each end must be a number or the id of a z-axis datum" };
+    }
+    const key = { sheet: planSheet.id, id: g.id };
+    for (const l of links) {
+      if (l.kind !== "same-entity") continue;
+      const other = l.a.sheet === key.sheet && l.a.id === key.id ? l.b : l.b.sheet === key.sheet && l.b.id === key.id ? l.a : null;
+      if (!other) continue;
+      const hit = uprightEntities.find((u) => u.sheet.id === other.sheet && u.g.id === other.id);
+      if (hit) return { z: hit.z, how: "link" };
+    }
+    const mineX = worldInterval(planSheet, g, 0);
+    const mineY = worldInterval(planSheet, g, 1);
+    if (mineX || mineY) {
+      const candidates = uprightEntities.filter((u) => !linkedAway.has(`${u.sheet.id}/${u.g.id ?? ""}`)).map((u) => {
+        const mine = u.axis === "x" ? mineX : mineY;
+        return { u, r: mine ? overlapRatio(mine, u.h) : 0 };
+      }).filter((x) => x.r >= 0.8);
+      if (candidates.length === 1) return { z: candidates[0].u.z, how: "match" };
+      if (candidates.length > 1) return { ambiguous: candidates.length };
+    }
+    return null;
+  }
+  for (const plan of plans) {
+    const map = mapper(plan);
+    const sheetId = plan.id ?? "?";
+    if (!map) {
+      for (const g of plan.groups ?? []) skipped.push({ id: `${sheetId}/${g.id ?? "?"}`, reason: "sheet has no world transform (transform.scale required)" });
+      continue;
+    }
+    for (const g of plan.groups ?? []) {
+      const gid = `${sheetId}/${g.id ?? "?"}`;
+      const isMember = !!(g.axis && g.section);
+      const isFootprint = !!(g.footprint && g.footprint.length >= 3);
+      if (!isMember && !isFootprint) continue;
+      if (isMember && !(g.section.w > 0 && g.section.d > 0)) {
+        skipped.push({ id: gid, reason: "invalid section \u2014 w and d must be positive world units" });
+        continue;
+      }
+      const zr0 = resolveZ(plan, g);
+      if (!zr0) {
+        skipped.push({ id: gid, reason: "no Z extent \u2014 add extrude datums/values, a same-entity link, or a matching elevation entity" });
+        continue;
+      }
+      if ("ambiguous" in zr0) {
+        skipped.push({ id: gid, reason: `ambiguous Z \u2014 ${zr0.ambiguous} elevation entities share this span; add a same-entity link to pick one` });
+        continue;
+      }
+      if ("error" in zr0) {
+        skipped.push({ id: gid, reason: zr0.error });
+        continue;
+      }
+      const zr = zr0;
+      const key = g.kind || (isMember ? "member" : "footprint");
+      if (!seenKey.has(key)) {
+        seenKey.add(key);
+        groupKeys.push(key);
+      }
+      if (isMember) {
+        const [ax, ay] = map(g.axis[0]);
+        const [bx, by] = map(g.axis[1]);
+        const zFrom = zr.how === "extrude" ? zr.z[0] : (zr.z[0] + zr.z[1]) / 2;
+        const zTo = zr.how === "extrude" ? zr.z[1] : zFrom;
+        elements.push({
+          id: g.id ?? gid,
+          group: key,
+          kind: "box",
+          from: [ax, ay, zFrom],
+          to: [bx, by, zTo],
+          section: { w: g.section.w, d: g.section.d },
+          meta: { sheet: sheetId, ...g.label ? { label: g.label } : {} }
+        });
+      } else {
+        elements.push({
+          id: g.id ?? gid,
+          group: key,
+          kind: "extrusion",
+          footprint: g.footprint.map((p) => map(p)),
+          from: Math.min(zr.z[0], zr.z[1]),
+          to: Math.max(zr.z[0], zr.z[1]),
+          meta: { sheet: sheetId, ...g.label ? { label: g.label } : {} }
+        });
+      }
+    }
+  }
+  const groups = groupKeys.map((key, i) => ({ key, label: key, color: PALETTE[i % PALETTE.length] }));
+  const name = contract.source && typeof contract.source.name === "string" ? String(contract.source.name) : "Reconstructed drawing";
+  return { scene: { meta: { name, units: "mm", up: "z" }, groups, elements }, skipped };
 }
 
 // steel-joints.ts
@@ -54516,12 +54728,13 @@ function contractToScene(contractInput) {
     const ptPerFt = plan.pt_per_ft && plan.pt_per_ft > 0 ? plan.pt_per_ft : 1;
     const defaultTosMm = (plan.default_tos ?? 0) * IN_TO_MM;
     for (const m of plan.members ?? []) {
-      const dims = profileDims(m.profile);
+      const explicit = m.section && typeof m.section.w === "number" && m.section.w > 0 && typeof m.section.d === "number" && m.section.d > 0 ? { w: m.section.w, d: m.section.d, approx: false } : null;
+      const dims = explicit ?? profileDims(m.profile);
       if (!dims || !Array.isArray(m.wp) || m.wp.length < 2) {
         skipped.push(m.id);
         continue;
       }
-      const profile = (m.profile ?? "").trim().toUpperCase();
+      const profile = (m.profile ?? "").trim().toUpperCase() || (explicit ? "CUSTOM" : "");
       if (!seenProfile.has(profile)) {
         seenProfile.add(profile);
         profileOrder.push(profile);
@@ -63865,6 +64078,15 @@ async function startServer() {
     async (req, reply) => {
       const doc = req.body && "contract" in req.body ? req.body.contract : readContract(req.params.appId);
       if (doc == null) return reply.status(404).send({ ok: false, error: "no contract to render" });
+      if (doc && typeof doc === "object" && doc.type === "drawing.vector/v1") {
+        const cleaned = postProcess(doc);
+        const v2 = validateContract(cleaned);
+        if (!v2.valid) {
+          const first = v2.errors[0];
+          return reply.status(400).send({ ok: false, error: `contract failed schema validation \u2014 ${first ? `${first.path}: ${first.message}` : "invalid"}` });
+        }
+        return { ok: true, ...viewsToScene(cleaned) };
+      }
       const v = validateSteelTakeoff(doc);
       if (!v.valid) {
         const first = v.errors[0];

package/dist/schemas/drawing.vector.v1.schema.json

@@ -27,6 +27,16 @@
       "type": "array",
       "items": { "$ref": "#/$defs/sheet" },
       "description": "One entry per page/view. Multi-page PDFs and image sets each become a sheet."
+    },
+    "datums": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/datum" },
+      "description": "READER-EMITTED world reference values (levels, grid lines) harvested from elevations/sections — the Z-ladder (or X/Y grid) that places 2D views in 3D. Top-level because a datum is a WORLD fact shared by every sheet; `sheet` records provenance. Multi-view reconstruction (views-to-scene) resolves groups[].extrude datum refs against these."
+    },
+    "links": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/link" },
+      "description": "READER-EMITTED cross-view correspondence hints: which entities in two sheets are the same object, which mark is a section cut of which region (the steel callouts[] analog). Keys are {sheet,id} composites — element/group ids are only sheet-unique."
     }
   },
   "$defs": {
@@ -57,7 +67,19 @@
             "scale":    { "type": "number", "description": "World units per display unit (e.g. mm per pt). Uniform." },
             "origin":   { "$ref": "#/$defs/point2", "description": "Display-space point mapped to world [0,0]." },
             "units":    { "type": "string", "description": "World units this maps into (overrides the top-level default for this sheet)." },
-            "rotation": { "type": "number", "description": "Degrees the display frame is rotated relative to world (page orientation)." }
+            "rotation": { "type": "number", "description": "Degrees to realign a rotated display frame with world axes. Applied by the reconstruction mapper as the standard math-positive matrix [cos -sin; sin cos] on display deltas about `origin` (display coords, Y-down), BEFORE scale and the Y-flip — i.e. content drawn rotated by R(-θ) is recovered with rotation: θ (locked by the views-to-scene rotation test)." }
+          },
+          "additionalProperties": true
+        },
+        "view": {
+          "type": "object",
+          "description": "READER-EMITTED view classification + third-axis binding — `transform` maps display->world in TWO axes but never says WHICH world axes; this does (a plan maps to X,Y at some Z; a south elevation maps to X,Z at some Y). Required for multi-view 3D reconstruction (views-to-scene); a sheet without it stays 2D-only. A wrong `dir`/`datum` silently mirrors or misplaces the model — the reader must cross-validate one known dimension per axis pair before emitting.",
+          "required": ["kind"],
+          "properties": {
+            "kind":  { "enum": ["plan", "elevation", "section", "detail"], "description": "What this sheet IS. Only plan/elevation/section participate in reconstruction." },
+            "dir":   { "enum": ["+z", "-z", "+x", "-x", "+y", "-y"], "description": "Observer look direction in world axes (a plan looks -z; a south elevation looks +y). Defaults: plan -z." },
+            "datum": { "type": "number", "description": "World offset (units) of the view plane along `dir`'s axis — plan: the projection Z; elevation/section: the plane's X or Y. Default 0." },
+            "depth": { "type": ["number", "null"], "description": "Section only: how far past the cut plane the view shows. null/absent = projection (shows everything)." }
           },
           "additionalProperties": true
         },
@@ -91,7 +113,7 @@
       "type": "object",
       "required": ["id", "kind"],
       "additionalProperties": true,
-      "description": "One drawing element. STABLE, sheet-unique `id` (assigned by the post-processor if the extractor omitted it) so it can be selected, exported, and targeted for modification.",
+      "description": "One drawing element. STABLE, sheet-unique `id`, REQUIRED on write (the store validates before the post-processor runs; the post-processor only repairs id collisions on read) — so every element can be selected, exported, and targeted for modification.",
       "properties": {
         "id":    { "type": "string", "description": "Stable, sheet-unique element id (e.g. 'e12')." },
         "kind":  { "enum": ["line", "arc", "polyline", "spline", "text"], "description": "Geometry class (broader than steel's line/text)." },
@@ -115,13 +137,79 @@
       "type": "object",
       "required": ["id"],
       "additionalProperties": true,
-      "description": "A named, ID-BEARING set of elements (a detected entity or a user grouping) — the unit an insert/modify Request can target.",
+      "description": "A named, ID-BEARING set of elements (a detected entity or a user grouping) — the unit an insert/modify Request can target, and the unit multi-view reconstruction lifts to 3D (via `section`/`axis` for member-like entities, `footprint`+`extrude` for extruded ones).",
       "properties": {
         "id":    { "type": "string", "description": "Stable, sheet-unique group id." },
-        "kind":  { "type": "string", "description": "Free-form entity kind (vocabulary-free; e.g. 'detail', 'wall', 'annotation'). The generic core does not enforce a taxonomy." },
+        "kind":  { "type": "string", "description": "Free-form entity kind (vocabulary-free; e.g. 'detail', 'wall', 'annotation', 'member', 'footprint'). The generic core does not enforce a taxonomy; views-to-scene keys on `section`/`axis`/`footprint`/`extrude` being present, not on kind." },
         "label": { "type": "string" },
         "elementIds": { "type": "array", "items": { "type": "string" }, "description": "The `elements[].id`s in this group." },
-        "confidence": { "type": "number", "minimum": 0, "maximum": 1, "description": "Reader-emitted grouping confidence 0..1." }
+        "confidence": { "type": "number", "minimum": 0, "maximum": 1, "description": "Reader-emitted grouping confidence 0..1." },
+        "section": {
+          "type": "object",
+          "required": ["w", "d"],
+          "description": "READER-EMITTED rectangular cross-section in WORLD units for a member-like entity — the vocabulary-free replacement for steel's AISC lookup; feeds the scene `section` as-is.",
+          "properties": { "w": { "type": "number", "exclusiveMinimum": 0 }, "d": { "type": "number", "exclusiveMinimum": 0 } },
+          "additionalProperties": true
+        },
+        "axis": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/point2" },
+          "minItems": 2,
+          "maxItems": 2,
+          "description": "Member work-line [[x0,y0],[x1,y1]] in THIS SHEET's display coords (mapped to world via transform+view). Paired with `section`."
+        },
+        "footprint": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/point2" },
+          "minItems": 3,
+          "description": "Closed outline (display coords, this sheet) of an extruded entity — a plate, wall, slab. Paired with `extrude`."
+        },
+        "extrude": {
+          "type": "object",
+          "description": "How far the entity extends along the sheet's missing axis (a plan's Z). Meaningful ONLY on PLAN-sheet groups — reconstruction builds geometry from plans; on elevation/section groups this field is ignored (those groups contribute extents, not bodies). Ends are datum ids (resolved against the top-level `datums`, z-axis only) or numbers (world units). views-to-scene can also INFER this by fold-line matching against a linked elevation when absent — but a PRESENT extrude that fails to resolve is an error, never silently replaced by inference.",
+          "properties": {
+            "from": { "type": ["string", "number"], "description": "Datum id or world value — the lower/near end." },
+            "to":   { "type": ["string", "number"], "description": "Datum id or world value — the upper/far end." }
+          },
+          "additionalProperties": true
+        }
+      }
+    },
+    "datum": {
+      "type": "object",
+      "required": ["id", "axis", "value"],
+      "additionalProperties": true,
+      "description": "One world reference value read off a drawing (a level line, a grid line). `value` is WORLD units on `axis`.",
+      "properties": {
+        "id":    { "type": "string", "description": "Document-unique datum id (e.g. 'lv1') — groups[].extrude references it." },
+        "kind":  { "enum": ["level", "grid"], "description": "level = a horizontal datum (Z); grid = a plan grid line (X or Y)." },
+        "label": { "type": "string", "description": "The as-drawn label (e.g. 'T.O.S. 16\\u2032-6\\u2033')." },
+        "axis":  { "enum": ["x", "y", "z"], "description": "Which world axis the value is on." },
+        "value": { "type": "number", "description": "World units (the contract's canonical units)." },
+        "sheet": { "type": "string", "description": "Provenance: the sheet id this datum was read from." },
+        "confidence": { "type": "number", "minimum": 0, "maximum": 1 }
+      }
+    },
+    "link": {
+      "type": "object",
+      "required": ["kind", "a", "b"],
+      "additionalProperties": true,
+      "description": "A cross-view correspondence hint between two {sheet,id} targets (ids are only sheet-unique — always composite keys).",
+      "properties": {
+        "kind": { "enum": ["same-entity", "cut-line", "datum-ref"], "description": "same-entity = the two targets are one object seen in two views; cut-line = a section mark and the sheet it cuts; datum-ref = an entity bound to a datum." },
+        "a": { "$ref": "#/$defs/linkEnd" },
+        "b": { "$ref": "#/$defs/linkEnd" },
+        "confidence": { "type": "number", "minimum": 0, "maximum": 1 }
+      }
+    },
+    "linkEnd": {
+      "type": "object",
+      "required": ["sheet"],
+      "additionalProperties": true,
+      "description": "One side of a link: a sheet and (usually) a group/element id on it.",
+      "properties": {
+        "sheet": { "type": "string" },
+        "id":    { "type": "string", "description": "A groups[].id or elements[].id on that sheet; absent = the whole sheet. NOTE: v1 reconstruction resolves same-entity links between GROUP ids only — an element-level link is kept as data but does not drive Z resolution yet." }
       }
     },
     "point2": {

package/dist/skills/floless-app-vectorize/SKILL.md

@@ -1,26 +1,33 @@
 ---
 name: floless-app-vectorize
-description: Vectorize a drawing into an editable drawing.vector/v1 contract in floless.app — the "Vectorize" reader. Triggers on a pending floless `rebake` request for the `vectorize` app (queued from its "Re-read & re-bake ▸" button), or asks like "vectorize this PDF", "turn my drawing into clean CAD linework", "read this detail into vectors", "trace this sheet". Teaches the host AI to run ONE deterministic PyMuPDF pass at COMPOSE time (no LLM, no API key) over a vector PDF, emit the drawing.vector/v1 contract, PUT it to the contract store, and hand the 2D vector editor to the user.
+description: Vectorize a drawing into an editable drawing.vector/v1 contract in floless.app — the "Vectorize" reader. Triggers on a pending floless `rebake` request for the `vectorize` app (queued from its "Re-read & re-bake ▸" button), or asks like "vectorize this PDF", "turn my sketch into clean CAD linework", "read this detail into vectors", "trace this photo". Teaches the host AI to read a drawing at COMPOSE time — a vector PDF via ONE deterministic PyMuPDF pass (no LLM), a scan/photo/hand sketch via AWARE's fenced vision.extract (schema-bound, cached) — emit the drawing.vector/v1 contract, PUT it to the contract store, and hand the 2D vector editor to the user.
 metadata:
-  version: 0.1.0
+  version: 0.3.0
 ---
 
 # Vectorize — read a drawing into a drawing.vector/v1 contract
 
 ## What this is
 
-`vectorize` is a FloLess app that turns a drawing (PDF today; scans/photos are a later
-slice) into clean, editable **2D vector linework** — a `drawing.vector/v1` contract
+`vectorize` is a FloLess app that turns a drawing — a vector PDF, a scan, a photo, a hand
+sketch — into clean, editable **2D vector linework**: a `drawing.vector/v1` contract
 (vocabulary-free; every element has a stable id) rendered in the 2D vector editor, where the
-user pans/zooms, toggles Lines/Curves/Text and layers, inspects weak traces, and exports SVG.
+user pans/zooms, toggles Lines/Curves/Text and layers, reviews weak traces, and exports SVG.
 
-The drawing is read **at compose time** with one deterministic PyMuPDF pass. There is **no
-model in the run path and no API key** — and for a vector PDF no vision either: the geometry
-is exact, extracted, never guessed. The app ships with a tiny hard-coded example; this skill
-is how the user's OWN drawing replaces it.
+The drawing is read **at compose time**, by one of two paths:
 
-**Later slices (mention as "next", do not attempt here):** raster/photo input via AWARE
-`vision.extract`, editor Save/edit, multi-view 3D reconstruction, DXF export.
+- **Vector PDF → deterministic.** One PyMuPDF pass; the geometry is exact, extracted, never
+  guessed. No model, no API key.
+- **Raster (scan/photo/sketch) → AWARE `vision.extract`.** The substrate's fenced extraction
+  carve-out: a FIXED schema + prompt + pinned model, content-hash cached (same input → same
+  JSON, no repeat model call). Coordinates come from the model, flagged with per-element
+  confidence the editor surfaces for review — never from you eyeballing pixels.
+
+There is **no model in the run path** either way. The app ships with a tiny hard-coded
+example; this skill is how the user's OWN drawing replaces it.
+
+**Later slices (mention as "next", do not attempt here):** multi-view 3D reconstruction,
+DXF export.
 
 > **Pasted a request?** If the user pastes a message beginning with a `[floless-request
 > type=rebake id=…]` marker, that's a request copied from the FloLess Dashboard — resolve it
@@ -39,14 +46,15 @@ prose, skip the lookup and proceed from that path. Resolve the port from the run
 floless.app (check `~/.floless/port` or the active server port), as the other floless-app
 skills do.
 
-### 2. Gate — is it a VECTOR PDF?
+### 2. Pick the path — vector or raster?
 
-This skill's deterministic path reads **vector** PDFs only. If `page.get_drawings()` returns
-nothing on every page (a scan, a photo, a hand sketch), **stop and say so honestly** — the
-raster/vision path is a later slice and is not shipped. Never trace pixels by eye into
-made-up coordinates; fabricated geometry is worse than no geometry.
+Probe the file: a PDF whose pages return `page.get_drawings()` paths is a **vector PDF** →
+step 3a (deterministic, always preferred). An image file, or a PDF with no vector paths (a
+scan, a photo, a hand sketch) → step 3b (vision). **Never trace pixels by eye into made-up
+coordinates** — fabricated geometry is worse than no geometry; the raster path exists so the
+extraction is fenced, cached, and confidence-flagged instead.
 
-### 3. Extract — one deterministic PyMuPDF pass
+### 3a. Vector path — one deterministic PyMuPDF pass
 
 Run the bundled extractor (it lives beside this file):
 
@@ -81,6 +89,36 @@ above is the contract. Hard schema requirements the server enforces on PUT: `typ
 dedupe, snap, or derive layers yourself — the server post-processes every read of this
 contract type.
 
+### 3b. Raster path — AWARE `vision.extract` (the fenced exception)
+
+For each raster image (or rasterized PDF page exported to an image):
+
+1. Copy `references/vision-inputs.template.json` (beside this file) to a scratch file and set
+   **only** `"file"` to the image's absolute path. The `prompt`, `schema`, and pinned `model`
+   are FIXED — together with the file bytes they form the extraction's content-hash cache key
+   and its fence; do not tweak them per run.
+2. Invoke the substrate:
+
+   ```
+   aware agent invoke vision extract --inputs @<scratch>/vision-inputs.json --json > <scratch>/vision-out.json
+   ```
+
+   A cache miss shells out to the local authenticated `claude`/`codex` CLI (no API key) and can
+   take a minute; a repeat of the same input replays from cache instantly. If neither CLI nor a
+   `vision-model` credential is available, stop and tell the user what to set up.
+3. Convert to the contract (the model traces in a normalized 0..1000 frame; this maps it onto
+   the image's real pixel size and carries per-element confidence):
+
+   ```
+   python <skill dir>/scripts/vision_to_contract.py <scratch>/vision-out.json <image> --out contract.json
+   ```
+
+   For a multi-image set, run steps 1–3 per image and append with
+   `--merge-into contract.json` instead of `--out`.
+4. Sanity-check the result before PUT: element count > 0, and the traced text you can see in
+   the vision output matches what the drawing actually says. A wildly wrong trace usually means
+   the image is too low-contrast — say so rather than shipping garbage.
+
 ### 4. Write to the contract store
 
 ```
@@ -101,10 +139,14 @@ Tell the user:
 
 - **What was read** — e.g. "2 sheets, 214 lines, 12 curves, 96 text spans from `detail.pdf`".
 - **Open the editor**: double-click the `read` node on the Vectorize canvas. It renders their
-  drawing — pan/zoom + Fit, Lines/Curves/Text toggles, per-layer toggles, weak-trace isolation
-  (deterministic reads have none), and **Export SVG**.
-- The editor is **view-only for now** — no Save/Approve path yet (a later slice); corrections
-  mean re-running this read with a better source.
+  drawing — pan/zoom + Fit, Lines/Curves/Text toggles, per-layer toggles, weak-trace isolation,
+  and **Export SVG**. Deterministic reads have no weak traces; after a **vision** read, point
+  the user at the **Confidence** panel — each trace the model was unsure about (confidence
+  < 0.5) is listed there with **Accept** (mark correct) and **Delete** (remove, with Undo), and
+  a "Reviewed N/M" counter tracks progress. Edits auto-save to the contract store.
+- **Approve & bake lock**: when satisfied, the user clicks Approve in the editor header — it
+  bakes the (edited) contract into the `read` node's `config.takeoff` and recompiles, arming
+  the Run gate. Never auto-approve on their behalf.
 
 ### 6. Clear the request
 
@@ -119,8 +161,11 @@ DELETE http://localhost:<port>/api/requests/<id>
 - **Compose-time only.** The drawing is read HERE, by the terminal AI, then PUT to the store.
   Never add a runtime node that reads the drawing — `aware app validate` rejects it, and it
   breaks determinism.
-- **Deterministic or nothing.** Vector geometry is extracted exactly; a raster with no vector
-  paths is out of scope until the vision slice ships. No eyeballed coordinates, ever.
+- **Deterministic first, fenced second, eyeballs never.** Vector geometry is extracted
+  exactly; raster interpretation goes ONLY through `vision.extract` (fixed schema/prompt/model,
+  cached, confidence-flagged). Never hand-write coordinates you read off pixels yourself, and
+  never swap the vision path for your own vision — the fence is what makes the extraction
+  reproducible.
 - **Thin-UI contract.** The browser recorded intent and the file path; the brain is the
   terminal AI. The UI never reads the drawing and never writes the contract itself.
 - **Stay in scope.** Producing and handing off the contract is the whole job — do not wire

package/dist/skills/floless-app-vectorize/references/vision-inputs.template.json

@@ -0,0 +1,40 @@
+{
+  "file": "<FILL IN: absolute path to the raster image/PDF>",
+  "model": "claude-sonnet-5",
+  "prompt": "Trace every visible stroke and label in this drawing into vector geometry. Use a coordinate frame where x runs 0..1000 left to right and y runs 0..1000 top to bottom over the full image. Emit each straight stroke as kind 'line' (exactly two points) or a connected run of straight strokes as 'polyline' (a vertex chain); follow smooth curves with a 'polyline' of enough vertices to track the curve (at most 20). Emit every piece of text as kind 'text' with the text content and its bounding box [x0,y0,x1,y1]. Mark a stroke dashed:true only if it is visibly drawn dashed. Do NOT invent geometry that is not visibly drawn; skip shading, hatching texture, smudges and paper artifacts. For every element report confidence between 0 and 1 — report 0.5 or lower whenever you are unsure the stroke exists, its endpoints are ambiguous, or the text is hard to read.",
+  "schema": {
+    "type": "object",
+    "required": ["elements"],
+    "properties": {
+      "elements": {
+        "type": "array",
+        "items": {
+          "type": "object",
+          "required": ["kind", "confidence"],
+          "allOf": [
+            { "if": { "properties": { "kind": { "enum": ["line", "polyline"] } } }, "then": { "required": ["pts"] } },
+            { "if": { "properties": { "kind": { "const": "text" } } }, "then": { "required": ["text", "bbox"] } }
+          ],
+          "properties": {
+            "kind": { "enum": ["line", "polyline", "text"] },
+            "pts": {
+              "type": "array",
+              "items": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 },
+              "description": "Vertices in the 0..1000 frame (line/polyline)"
+            },
+            "text": { "type": "string" },
+            "bbox": {
+              "type": "array",
+              "items": { "type": "number" },
+              "minItems": 4,
+              "maxItems": 4,
+              "description": "[x0,y0,x1,y1] in the 0..1000 frame (text)"
+            },
+            "dashed": { "type": "boolean" },
+            "confidence": { "type": "number", "minimum": 0, "maximum": 1 }
+          }
+        }
+      }
+    }
+  }
+}