forgecad 0.9.2 → 0.9.3

package/dist/docs-raw/generated/viewport.md

@@ -9,7 +9,7 @@ Cut planes, exploded views, joint animations, and scene configuration.
 
 ## Contents
 
-- [Viewport & Runtime](#viewport-runtime) — `scene`, `viewConfig`, `explodeView`, `jointsView`, `cutPlane`, `mock`, `showLabels`, `highlight`
+- [Viewport & Runtime](#viewport-runtime) — `Viewport.label`, `scene`, `viewConfig`, `explodeView`, `jointsView`, `cutPlane`, `mock`, `showLabels`, `highlight`
 - [RouteBuilder](#routebuilder)
 - [route](#route)
 
@@ -17,14 +17,50 @@ Cut planes, exploded views, joint animations, and scene configuration.
 
 ### Viewport & Runtime
 
+#### `Viewport.label()` — Add a render-only viewport label at a world-space point.
+
+`Viewport.label()` is for explanatory text that helps a viewer understand the model. It does not create sketches, meshes, B-rep topology, exported text, or face labels, so it stays off the OCCT path. Use [`text2d()`](/docs/sketch#text2d) only when the letters should become manufactured geometry, such as raised lettering, engraved serial numbers, or exported nameplates.
+
+Labels are collected during script execution and rendered by the viewport as lightweight overlay annotations. They are ignored by exports and do not appear in `objects`.
+
+```js
+Viewport.label('Bearing bore', [0, 0, 18], {
+  color: '#f8fafc',
+  background: '#0f172acc',
+  offset: [0, 0, 8],
+  anchor: 'bottom',
+});
+
+return box(40, 30, 12);
+```
+
+```ts
+Viewport.label(text: string, at: [ number, number, number ], options?: RenderLabelOptions): void
+```
+
+**`RenderLabelOptions`**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `color?` | `string` | Text color as any CSS color string. |
+| `background?` | `string` | Background color as any CSS color string. Use `'transparent'` for no pill background. |
+| `size?` | `number` | Font size in CSS pixels. Defaults to 12. |
+| `offset?` | `[ number, number, number ]` | Additional world-space offset from `at`. |
+| `anchor?` | `RenderLabelAnchor` | Which point of the label box is anchored to `at`. Defaults to `'center'`. |
+| `alwaysOnTop?` | `boolean` | When false, the label is hidden when occluded by scene geometry. Defaults to true. |
+
 #### `scene()` — Configure the scene environment for the current script execution.
 
-Controls camera position, lighting rig, background color or gradient, atmospheric fog, environment maps, post-processing effects, and capture parameters for the `forgecad capture` command. Multiple calls merge — later values override earlier ones on a per-key basis, so you can split configuration across multiple `scene()` calls.
+Controls camera position, named render views, optional model journeys, lighting rig, background color or gradient, atmospheric fog, environment maps, post-processing effects, and capture parameters for the `forgecad capture` command. Multiple calls merge — later values override earlier ones on a per-key basis, so you can split configuration across multiple `scene()` calls.
 
 When `lights` is specified, **all** default lights are removed. You must include your own ambient light or the scene will be fully dark.
 
 Setting `camera.position` overrides auto-framing — the viewport will no longer auto-fit the geometry on script reload.
 
+Named render views let scripts check in repeatable cameras next to the model code. The canonical shape is `{ camera: { position, target } }`, and a direct camera shorthand `{ position, target }` is also accepted. Use the canonical shape when you may add view metadata later. Use it from the CLI with `forgecad render 3d model.forge.js --view hero`.
+
+Model journeys let scripts check in a compact guided path through named objects. Each journey has ordered `steps`; each step can name a `focus` target by object name/tree path, provide a caption, and optionally provide an explicit camera. In the viewer, journeys are opt-in: they appear as a small Explore control and do not move the camera until the user starts them. Use `forgecad run model.forge.js --journeys` or `--journeys-json` to inspect resolved targets.
+
 Post-processing effects (`bloom`, `vignette`, `grain`) work in the browser viewport only. The CLI applies camera, lights, background, fog, and `toneMappingExposure` but skips shader effects.
 
 All numeric values accept `param()` expressions.
@@ -33,6 +69,22 @@ All numeric values accept `param()` expressions.
 scene({
   background: { top: '#000814', bottom: '#001d3d' },
   camera: { position: [160, -120, 100], target: [0, 0, 50], fov: 52 },
+  views: {
+    hero: {
+      camera: { position: [180, -140, 90], target: [0, 0, 25], up: [0, 0, 1], fov: 38 },
+    },
+    side: { position: [240, 0, 70], target: [0, 0, 25], fov: 34 },
+  },
+  journeys: {
+    grandTour: {
+      title: 'Grand Tour',
+      startsAt: 'overview',
+      steps: [
+        { id: 'overview', focus: 'Solar System', caption: 'Start with the whole model.' },
+        { id: 'earth', focus: 'Earth', caption: 'Fit and inspect Earth.' },
+      ],
+    },
+  },
   lights: [
     { type: 'ambient', color: '#001233', intensity: 0.08 },
     { type: 'point', position: [120, -80, 130], color: '#00f5d4', intensity: 4, distance: 400, decay: 1 },
@@ -59,12 +111,38 @@ scene(options: SceneOptions): void
 | Option | Type | Description |
 |--------|------|-------------|
 | `capture?` | `SceneCaptureConfig` | Default capture parameters for `forgecad capture` — CLI flags override these. |
-| `background?`, `camera?`, `lights?`, `environment?`, `fog?`, `postProcessing?`, `ground?` | | — |
+| `background?`, `camera?`, `views?`, `journeys?`, `lights?`, `environment?`, `fog?`, `postProcessing?`, `ground?` | | — |
 
 `SceneBackgroundGradient`: `{ top: string, bottom: string }`
 
 **`SceneCameraConfig`**: `position?: [ number, number, number ]`, `target?: [ number, number, number ]`, `up?: [ number, number, number ]`, `fov?: number`, `type?: "perspective" | "orthographic"`
 
+**`SceneJourneyConfig`**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `title?` | `string` | Viewer-facing journey title. Defaults to the journey id. |
+| `startsAt?` | `string` | Optional starting step id. Defaults to the first step. |
+| `behavior?` | `"opt-in" \| "auto"` | Whether the viewer should offer or auto-open the journey. First slice supports opt-in. |
+| `steps` | `SceneJourneyStepConfig[]` | Ordered journey spine. Branches can be added later without changing this core contract. |
+| `valid?` | `boolean` | True unless any journey or step diagnostic has level "error". |
+| `diagnostics?` | `SceneJourneyDiagnostic[]` | Whole-journey diagnostics, including unresolved startsAt and step target diagnostics. |
+
+**`SceneJourneyStepConfig`**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `id` | `string` | Stable step id used by viewer links and Next/Back state. |
+| `title?` | `string` | Viewer-facing title. Defaults to the step id. |
+| `focus?` | `string` | Object name or slash-separated tree path to focus. |
+| `caption?` | `string` | Short optional viewer caption. |
+| `camera?` | `SceneViewCameraConfig` | Optional explicit camera for this step. When omitted, the viewer fits `focus`. |
+| `resolvedFocusId?` | `string \| null` | Resolved object id after script execution, when `focus` matched exactly one object. |
+| `resolvedFocusPath?` | `string \| null` | Resolved object tree path or name after script execution. |
+| `diagnostics?` | `SceneJourneyDiagnostic[]` | Resolution diagnostics for this step. |
+
+`SceneJourneyDiagnostic`: `{ level: SceneJourneyDiagnosticLevel, message: string, stepId?: string, suggestions?: string[] }`
+
 **`SceneLightConfig`**
 
 | Option | Type | Description |

package/dist/docs-raw/product/user-outreach-email-templates.md

@@ -0,0 +1,159 @@
+# User Outreach Email Templates
+
+Use these templates for personal outreach to ForgeCAD users. They are intentionally written in a founder/operator voice: warm, specific, curious, and useful. The goal is to learn from real projects, make users feel supported, and open the door to deeper onboarding when it makes sense.
+
+## Shared Guidance
+
+- Personalize the first sentence with one real signal when possible: plan tier, recent activity, project name, export type, team domain, or signup source.
+- Keep the ask small. A 20-minute chat is easier to accept than a vague "feedback call."
+- Do not make the user prove they are important. The default posture is: if they are using ForgeCAD, their workflow matters.
+- For Pro users, make support and team onboarding explicit. They already crossed the trust line.
+- For active free users, lead with curiosity. Mention Pro only as a practical fit for commercial work, not as the reason for the email.
+
+## Pro User Templates
+
+### 1. Welcome And Use Case Discovery
+
+**Subject:** Welcome to ForgeCAD Pro
+
+Hi {{first_name}},
+
+I saw that you upgraded to ForgeCAD Pro. Thank you for trusting us with your work.
+
+I wanted to reach out personally because we are still early enough that real professional use cases can directly shape the product. If you are using ForgeCAD for client work, a product, internal tooling, robotics, 3D printing, fixtures, or anything else serious, I would love to understand what you are building and where the tool should become sharper for you.
+
+Would you be open to a 20-minute call this week or next? I can help with onboarding, answer workflow questions, and learn what would make ForgeCAD more useful for your day-to-day work.
+
+Best,
+
+{{sender_name}}
+
+### 2. Team Onboarding Exploration
+
+**Subject:** Helping your team get further with ForgeCAD
+
+Hi {{first_name}},
+
+Thanks again for using ForgeCAD Pro. I wanted to check whether you are using it mostly on your own, or whether there are other people on your team who might need to work with the same models, project files, exports, or review flow.
+
+If there is a team workflow behind your ForgeCAD use, I would be happy to help you think through the setup: local project structure, CLI usage, shared browser projects, AI-assisted modeling, exports, and any support expectations around commercial work.
+
+Would it be useful to set up a short onboarding call? Even if you are not ready to add more people yet, it would help us understand what serious team adoption should feel like.
+
+Best,
+
+{{sender_name}}
+
+### 3. Pro Check-In After Usage
+
+**Subject:** How is ForgeCAD Pro fitting into your work?
+
+Hi {{first_name}},
+
+I wanted to check in now that you have had some time with ForgeCAD Pro.
+
+The main thing I would love to understand is: what job are you trying to get done with ForgeCAD, and where does the product currently help the most or slow you down?
+
+If you have a real project in progress, I am happy to look at the workflow with you. A short call would help us support you better, and it would also help us decide which Pro and team features should come next.
+
+Best,
+
+{{sender_name}}
+
+## Active User Templates
+
+### 1. Curious Product Discovery
+
+**Subject:** Curious what you are building with ForgeCAD
+
+Hi {{first_name}},
+
+I noticed you have been active in ForgeCAD recently, and I wanted to reach out personally.
+
+We are trying to understand what people are actually building: quick 3D-printable parts, mechanical assemblies, robotics ideas, fixtures, generated geometry, design automation, or something completely different. The product gets much better when we can see the real use cases behind the activity.
+
+Would you be open to a 20-minute chat? I would mostly like to learn what you are working on, what feels promising, and what currently gets in your way.
+
+Best,
+
+{{sender_name}}
+
+### 2. Active User With Commercial Hint
+
+**Subject:** Learning from your ForgeCAD workflow
+
+Hi {{first_name}},
+
+I saw you have been using ForgeCAD and wanted to ask what kind of work you are exploring with it.
+
+If this is personal, learning, open-source, or experimental work, I would simply love to understand the project and what would make ForgeCAD more enjoyable or capable for you. If you are using it commercially, ForgeCAD Pro may be the right fit, and I am happy to explain that too, but that is not the main reason I am writing.
+
+The main reason is that active users teach us where the product is strong, where it is confusing, and what workflows deserve more attention.
+
+Would you be open to a quick call?
+
+Best,
+
+{{sender_name}}
+
+### 3. High-Activity User Check-In
+
+**Subject:** Quick ForgeCAD question
+
+Hi {{first_name}},
+
+I noticed you have spent real time with ForgeCAD, so I wanted to ask one direct question:
+
+What are you trying to make with it?
+
+We are early, and this is the stage where understanding real projects matters more than polished surveys. If ForgeCAD is helping, I would like to know why. If something is awkward, missing, or confusing, I would like to know that even more.
+
+Would you be open to a short chat this week or next?
+
+Best,
+
+{{sender_name}}
+
+## Follow-Up Templates
+
+### 1. Gentle Follow-Up
+
+**Subject:** Re: {{previous_subject}}
+
+Hi {{first_name}},
+
+Just wanted to follow up once in case this got buried.
+
+I would still be very interested to hear what you are using ForgeCAD for. Even a two-sentence reply would be useful if a call is too much right now.
+
+Best,
+
+{{sender_name}}
+
+### 2. Concrete Reply Prompt
+
+**Subject:** Re: {{previous_subject}}
+
+Hi {{first_name}},
+
+One quick follow-up. If a call is not convenient, could you reply with whichever of these is closest?
+
+1. I am using ForgeCAD for personal projects or learning.
+2. I am evaluating it for commercial work.
+3. I am trying to use it with a team.
+4. I am stuck or missing something important.
+
+That alone would help us understand how to support you better.
+
+Best,
+
+{{sender_name}}
+
+## Placeholder Checklist
+
+| Placeholder | Meaning |
+|---|---|
+| `{{first_name}}` | User first name when known, otherwise use `there` |
+| `{{sender_name}}` | Founder/operator name |
+| `{{previous_subject}}` | Subject line from the first outreach email |
+| `{{project_signal}}` | Optional project, command, export, or activity signal for manual personalization |

package/dist/docs-raw/skills/forgecad-image-replicator.md

@@ -59,7 +59,7 @@ Reference matching is a validation step after the object exists.
    - validation views and inspection channels
 
 4. Choose the modeling structure.
-   Use a multi-file `main.forge.js` project when the object has distinct parts, repeated feature families, internals, purchased hardware, variants, or meaningful manufacturing assumptions. Keep dimensions, materials, part builders, hardware ghosts, and assembly helpers in neighboring plain `.js` files.
+   Use a multi-file `main.forge.js` project when the object has distinct parts, repeated feature families, internals, purchased hardware, variants, or meaningful manufacturing assumptions. Put renderable/importable parts and sub-assemblies in neighboring `.forge.js` files; keep only pure dimensions, materials, math helpers, and lookup tables in plain `.js` files.
 
 5. Build a coarse 3D blockout.
    Model the object, not the image. Start with the large volumes, axes, symmetry, side depth, rear form, underside, and hidden continuations. Render canonical views before doing reference-camera comparison.

package/dist/docs-raw/skills/forgecad-make-a-model.md

@@ -20,7 +20,8 @@ All new `.forge.js` files go under the date-based directory structure:
 ```
 YYYY/MM/DD/file.forge.js          — single-file model
 YYYY/MM/DD/folder/main.forge.js   — multi-file project entry point
-YYYY/MM/DD/folder/*.js            — shared helpers, constants, parts, assemblies
+YYYY/MM/DD/folder/parts/*.forge.js — standalone/importable model parts
+YYYY/MM/DD/folder/lib/*.js        — pure helpers/constants only, no geometry return
 ```
 
 Use today's date for the directory. Use the user's current ForgeCAD project when one is available; otherwise use a clearly named local model folder.
@@ -30,8 +31,9 @@ Use today's date for the directory. Use the user's current ForgeCAD project when
 - Use kebab-case for file and folder names: `parametric-lego.forge.js`
 - Use descriptive names that communicate what the model is
 - For any multi-file project, name the runnable ForgeCAD entry point `main.forge.js`
-- If a model needs shared helpers, put them in a subfolder as plain `.js` files (not `.forge.js`)
-- Do not create multiple `.forge.js` files in the same project folder unless they are intentionally separate runnable models
+- Put renderable/importable parts and sub-assemblies in separate `.forge.js` files when splitting is justified; each should be standalone-runnable and importable with `require('./parts/name.forge.js', params)`.
+- Use plain `.js` files only for pure constants, math helpers, tables, or formatting code that does not construct and return ForgeCAD geometry.
+- Do not create multiple `.forge.js` files merely for organization; split only for reusable parts, large self-contained components, or independent sub-assemblies.
 
 ### Workflow
 
@@ -39,12 +41,13 @@ Use today's date for the directory. Use the user's current ForgeCAD project when
 2. Create the directory — `mkdir -p YYYY/MM/DD/[folder]` as needed.
 3. Write the model — create the `.forge.js` file(s) following ForgeCAD conventions:
    - Declare `param()` / `boolParam()` for all tunable dimensions
-   - If the model is split across files, use `main.forge.js` as the only primary `.forge.js` entry point and import helpers/parts from neighboring plain `.js` modules
+   - If the model is split across files, use `main.forge.js` as the primary entry point, import renderable parts from neighboring `.forge.js` files, and keep only pure helpers/constants in plain `.js` modules
    - When there are multiple versions of the same object, expose the version as a choice parameter and render one selected version at a time
    - Use clear variable names
    - Build any implied internal structure as real geometry, even when it will be hidden in the final view
    - Make final mating geometry physically plausible: parts may touch, clear each other, or be boolean-joined, but should not unintentionally pass through each other
    - Return the final geometry (single shape, array, or named objects array)
+   - Avoid expensive global edge treatment on repeated decorative geometry: do not call `fillet(shape, r)` or `chamfer(shape, r)` on every edge of large unioned/repeated parts unless the render/run loop proves it is fast enough. Prefer simpler primitive profiles, lower segment counts, or targeted edge selectors.
 4. Validate — run `forgecad run <file>` to check for errors. For multi-file projects, always validate `main.forge.js`.
 5. Verify geometry — render the result and run `forgecad render inspect` with the relevant channels for the task (see Render-Verify Loop below). For multi-file projects, render and inspect `main.forge.js`.
 
@@ -294,6 +297,32 @@ scene({
 });
 ```
 
+#### Named render views
+
+For models that need repeatable review, docs, or hero renders, declare named views inside
+`scene({ views })`. The canonical form wraps each camera in `{ camera: ... }`; direct camera
+shorthand is accepted by the runtime, but the wrapped form is the clearest prompt/example shape.
+
+```js
+scene({
+  camera: { position: [430, -540, 340], target: [0, 30, 125], fov: 38 },
+  views: {
+    hero: {
+      camera: { position: [430, -540, 340], target: [0, 30, 125], up: [0, 0, 1], fov: 38 },
+    },
+    side: {
+      camera: { position: [700, 0, 180], target: [0, 30, 100], up: [0, 0, 1], fov: 32 },
+    },
+  },
+});
+```
+
+Render one later with:
+
+```bash
+forgecad render 3d model.forge.js --view hero
+```
+
 #### Lighting principles
 
 - When `lights` is set, all defaults are replaced, so always include an ambient light or the scene goes black.

package/dist/docs-raw/skills/forgecad-prepare-prompt.md

@@ -162,7 +162,7 @@ By the end of this skill, there should be:
    - purchased-part boundary
    - validation standard
    - variant-selection policy when multiple versions of the same object are requested
-   - file-organization policy: if the implementation needs multiple files, the runnable ForgeCAD entry point must be `main.forge.js`, with helpers/parts/constants in neighboring plain `.js` modules
+   - file-organization policy: if the implementation needs multiple files, the runnable ForgeCAD entry point must be `main.forge.js`; renderable parts/sub-assemblies belong in neighboring `.forge.js` files, while plain `.js` files are only for pure helpers/constants
    - explicit uncertainty policy
 
 8. Emit one master prompt.

package/dist/docs-raw/skills/forgecad-project.md

@@ -13,7 +13,7 @@ ForgeCAD project CLI workflow — creating, managing, syncing projects and files
 
 ### Overview
 
-**forgecad.io** is the primary platform for ForgeCAD projects. The CLI is the main way AI agents interact with it — creating projects, managing files, publishing models, and collaborating. `forgecad studio <project-path> [project-path ...]` / `forgecad dev <project-path> [project-path ...]` run the editor locally for offline work.
+**forgecad.io** is the primary platform for ForgeCAD projects. The CLI is the main way AI agents interact with it — creating projects, managing files, publishing models, and collaborating. `forgecad studio <project-path> [project-path ...]` opens the installed local editor for users; `forgecad dev <project-path> [project-path ...]` is mainly for ForgeCAD source development.
 
 ### Authentication
 

package/dist/docs-raw/skills/forgecad-render-inspect.md

@@ -43,7 +43,7 @@ Routing:
    Use `/tmp/<model-name>-inspect` by default so generated PNGs do not dirty the repo. Use a project output directory only when the user wants a persistent artifact.
 
 3. Pick the channel set.
-   Use the table below. Prefer small targeted channel sets; the full channel set is expensive and should be reserved for an explicit stress check.
+   Use the table below. Prefer small targeted channel sets; broad stress checks should still list explicit channels.
 
 4. Run the command.
    In the ForgeCAD repo, prefer the built CLI when you want the current checkout:

package/dist/docs-raw/skills/forgecad.md

@@ -27,7 +27,8 @@ Author or modify ForgeCAD models, sketches, assemblies, and CLI workflows. Prefe
 
 #### Import and Composition
 
-- `require("./file.forge.js", { Param: value })` for any model file, with optional param overrides.
+- Always include the extension in relative imports: `require("./file.forge.js", { Param: value })` for model files and `require("./helpers.js")` for plain helper modules. Do not write extensionless imports such as `require("./file")`; ForgeCAD resolves project imports by exact path.
+- ForgeCAD APIs are injected globals in `.forge.js` files. Use `bom()`, `box()`, `scene()`, `Shape`, etc. directly; do not destructure those names from helpers with patterns like `const { bom } = require("./bom.js")`. If a helper file is needed, import it under a project-specific name such as `const bomHelpers = require("./bom.js")`.
 - For static multi-part models, connectors + `matchTo()` are the default way to assemble touching parts.
 - Top-level scripts can return `Assembly` or `SolvedAssembly` directly. Do not call `.toGroup()` just to render an assembly; use `.toGroup()` only when you need `ShapeGroup` composition, transforms, or named-child lookup.
 - `importSvgSketch()` for SVG files (file format loader, not a module import).