@deepblend/dsh-blender-bundle 0.1.0

package/README.md

@@ -0,0 +1,86 @@
+# @deepblend/dsh-blender-bundle
+
+The **installable composition** of DeepBlend Studio — a Blender 3D animation workbench for
+[DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness), where **SceneSpec is the
+source of truth and `.blend` is a compiled artifact**.
+
+This is the directory the plugin list's entry points at, so here is what it is, and what it is
+not.
+
+## Install
+
+From source:
+
+```sh
+dsh plugin --profile web add 'github:pearjelly/deep-blend#path:/packages/deepblend/bundle'
+```
+
+Or from the prebuilt release artifact, which resolves nothing:
+
+```sh
+dsh plugin --profile web add https://github.com/pearjelly/deep-blend/releases/latest/download/deepblend-bundle.tgz
+```
+
+Then restart `dsh web`. A new session can select the **DeepBlend Studio** preset, and the
+workbench appears in the sidebar.
+
+## What is in here
+
+| file | what it is |
+|---|---|
+| `cordis.patch.yml` | the composition — four rows and the configuration they mount with |
+| `lib/index.js` | exports `PATCH_FILE` and `ROW_IDS`; it exists so the package is a well-formed importable ESM package |
+| `screenshots.json` | the storefront's screenshot manifest |
+
+There is no runtime code in this package, and that is deliberate rather than an omission.
+
+## How it works
+
+The patch mounts four rows:
+
+| row | package | what it publishes |
+|---|---|---|
+| `deepblend-blender-runtime` | `@deepblend/dsh-blender-provider-local` | the Blender execution seam |
+| `deepblend-blender-host` | `@deepblend/dsh-blender-host` | the business facade both planes read |
+| `deepblend-blender-ui` | `@deepblend/dsh-blender-ui` | the browser-facing host half |
+| `deepblend-blender-preset` | `@deepblend/dsh-blender-preset` | deploys the agent presets |
+
+The model-visible tools are deliberately **not** registered here. A preset decides what one
+session's model may see, so registering them in the host composition would hand the Blender
+toolset to every session in the process — the last row is what delivers them, into
+`<DSH_HOME>/.agent-presets/`, once per process.
+
+## Why this is not a meta-package
+
+The plugin list does not list a bundle whose only content is a dependency list. This one is not
+that, and the three checks are the market's own rather than our argument:
+
+- **The gate requires this shape.** A submission must point at a package declaring `dsh.bundle`.
+  Exactly one package in this repository does, and it is this one — there is no other package the
+  gate would accept.
+- **The shape is already listed.** Eight entries on the list point at a `packages/bundle`
+  directory, across six categories. One of them, `ayahunter/dsh-trail`, is a patch with a single
+  row and a single dependency and no source at all. This one composes four rows and configures
+  them.
+- **It points at no other entry.** The six dependencies are this repository's own internal
+  modules — the contracts, the execution seam, the facade, the browser half, the tool plane and
+  the preset deployer — not other plugins on the list, so the double-counting that rule exists to
+  prevent cannot occur.
+
+The full audit, with the readings behind it, is in
+[`deepblend/docs/listing-entry.yml`](../../../deepblend/docs/listing-entry.yml) — the file the submitted entry
+is generated from.
+
+## Where the product lives
+
+| package | |
+|---|---|
+| [`../contracts`](../contracts) | SceneSpec, the schemas, the visual-issue vocabulary |
+| [`../provider-local`](../provider-local) | controlled `bpy` execution and the SceneSpec compiler |
+| [`../host`](../host) | the business facade: projects, revisions, render jobs, the visual loop |
+| [`../ui`](../ui) | the workbench's host half and browser client |
+| [`../tool`](../tool) | the model-visible tool plane |
+| [`../preset`](../preset) | the agent presets and the deployer that installs them |
+
+The repository root has the [full README](../../../README.md), and
+[`deepblend/docs/`](../../../deepblend/docs) has the manuals.

package/cordis.patch.yml

@@ -0,0 +1,219 @@
+# DeepBlend Studio Host Bundle — the HOST COMPOSITION layer (SPEC §4.1, §18).
+#
+# This patch adds one `insert` over the profile tree. It carries only
+# process-level, cross-session capability:
+#
+#   deepblend-blender-runtime  → publishes `blenderRuntime`  (Blender execution seam)
+#   deepblend-blender-host     → publishes `blenderStudio`   (business facade)
+#   deepblend-blender-ui       → publishes `blenderUi`       (browser-facing host half)
+#
+# The model-visible tool (`blender_capabilities`) deliberately does NOT live
+# here. It belongs to the AGENT PRESET, because a preset decides what one
+# session's model may see (SPEC §4.2, §4.3). Registering it here would expose
+# the tool to every session in the process.
+#
+# ─────────────────────────────────────────────────────────────────────────────
+# WHY THERE IS NOT ONE `!!js` EXPRESSION HERE
+#
+# The obvious spelling for a machine-dependent value would be
+# `!!js process.env.X || …`, and it does NOT work. The loader interpolates `!!js`
+# through
+#
+#     new Function('ctx', 'with (ctx) { return eval(expr) }')
+#
+# evaluated against the **Loader context**, not the global object. `process` is
+# not a Loader-context property, so any `!!js … process …` expression throws a
+# ReferenceError at compose time. The failure is silent and deeply confusing:
+# the row still mounts, the config key simply keeps its schema default, and the
+# service then fails later at first use. That is exactly how `blenderPath` came
+# up as the literal `'blender'` instead of the installed binary.
+#
+# `!!js` remains correct for expressions referencing only Loader-context values
+# (which is how the shipped bundles use it). It is not a general escape hatch
+# to Node globals.
+#
+# So this file cannot compute a path at all, and the answer M5 arrived at is that
+# it should not try: every machine-dependent value is now a DEFAULT inside the
+# package that owns it, computed from `DSH_HOME` or from the package's own
+# location. See the note above the first row.
+#
+# OVERRIDING THESE VALUES: a row's `config` is replaced wholesale, not merged
+# (measured — architecture-decisions D74), so the operator layer
+# ($DSH_HOME/profiles/<name>/cordis.patch.yml) must restate every key it wants to
+# keep. To pin storage to a directory of your own:
+#
+#     - id: deepblend-blender-runtime
+#       config:
+#         timeoutMs: 180000
+#         maxOutputBytes: 1048576
+#         maxSpillBytes: 67108864
+#         executableAllowlist: []
+#         capabilitiesCacheMs: 60000
+#         keepWorkingDirectory: false
+#         workspaceRoot: /path/to/workspace
+#
+#     - id: deepblend-blender-host
+#       config:
+#         maxPreviewSamples: 512
+#         maxVisualIterations: 5
+#         minVisualConfidenceForAutoFix: 0.8
+#         stopOnRepeatedIssueCount: 2
+#         visualReviewProvider: deepseek-official
+#         visualReviewModel: deepseek-flash
+#         visualReviewMaxTokens: 24000
+#         visualReviewViews: [active-camera, three-quarter, top, detail]
+#         finalRenderProfile: final
+#         maxFinalSamples: 4096
+#         ffmpegPath: ffmpeg
+#         ffprobePath: ffprobe
+#         encodeCrf: 18
+#         encodePreset: medium
+#         requireApprovalAboveFrames: 900
+#         progressPollMs: 1000
+#         reconcileOnStart: true
+#         workspaceRoot: /path/to/workspace
+# ─────────────────────────────────────────────────────────────────────────────
+
+- insert:
+    # Blender execution seam. `ctx.subprocess` is a declared injection, so this
+    # row parks in `waiting` — visibly — rather than failing later at first call.
+    #
+    # THIS ROW NAMES NO PATH, AND THAT IS THE POINT. Until M5 it carried five
+    # literal absolute paths — an absolute Blender binary, an absolute
+    # bootstrap.py, an absolute workspace root, that root's projects directory,
+    # and an allowlist entry — which meant the bundle composed rows pointing at
+    # one developer's home directory. On any other machine the product mounted,
+    # reported healthy, and then failed at first render; `--dump-config` looked
+    # correct throughout, because the values WERE what the file said.
+    #
+    # `!!js` could not be used to fix it: it is evaluated against the Loader
+    # context, where `process` does not exist (M0 §4.2, verified). So the defaults
+    # moved into the packages, where they are ordinary Node code that can look at
+    # its own location and at `DSH_HOME`:
+    #
+    #   blenderPath   'auto'  -> the managed install if present, else PATH
+    #   bootstrapPath ''      -> the copy shipped inside the provider package
+    #   workspaceRoot ''      -> <DSH_HOME>/deepblend            (SPEC §17)
+    #   projectsRoot  ''      -> <workspaceRoot>/projects        (SPEC §13)
+    #
+    # An operator who wants a different location sets it in the operator layer
+    # ($DSH_HOME/profiles/<name>/cordis.patch.yml). Note that a layer's `config`
+    # REPLACES this one wholesale rather than merging into it — measured, see
+    # architecture-decisions D74 — so such a layer must restate every key it wants
+    # to keep.
+    #
+    # The portability of this file is asserted, not assumed:
+    # `contract/bundle-portability.test.mjs` fails on any absolute path here.
+    - id: deepblend-blender-runtime
+      name: '@deepblend/dsh-blender-provider-local'
+      config:
+        # A cold Blender launch plus one 64x36 render probe; measured ~0.4 s on
+        # the M0 machine, so 180 s is a generous ceiling rather than a real budget.
+        timeoutMs: 180000
+        maxOutputBytes: 1048576
+        maxSpillBytes: 67108864
+        # Extra executable allowlist roots beyond the built-in defaults
+        # (/Applications, /opt/homebrew/bin, /usr/local/bin, ~/Applications).
+        # An absolute `blenderPath` is trusted as a deliberate operator choice;
+        # this list matters when the path is a bare name resolved through PATH.
+        executableAllowlist: []
+        # Capabilities are stable within a session; re-probe explicitly by
+        # calling the tool with refresh=true.
+        capabilitiesCacheMs: 60000
+        # Retaining temp dirs is a debugging aid; off by default so a probe
+        # leaves no residue behind.
+        keepWorkingDirectory: false
+
+    # Business facade consumed by BOTH planes: the preset tool and the UI host
+    # half read the same authoritative answer (SPEC §14.3).
+    - id: deepblend-blender-host
+      name: '@deepblend/dsh-blender-host'
+      config:
+        # `projectsRoot` and `workspaceRoot` are deliberately absent for the same
+        # reason as the paths above; both rows resolve them from `DSH_HOME`, and
+        # because they resolve them through ONE helper they cannot disagree —
+        # which is what the paragraph that used to sit here asked a human to
+        # arrange ("MUST equal the runtime row's workspaceRoot"). A comment is not
+        # a constraint; a shared function is.
+        # Hard ceiling on preview cost, applied on top of the per-profile
+        # `maxSamplesBudget` (SPEC §15.4 render-cost threshold).
+        maxPreviewSamples: 512
+
+        # ── M2: the visual loop ──────────────────────────────────────────────
+        # SPEC §17 groups these under `agent`; they belong to the HOST because the
+        # loop they bound is host-owned (decision D34): the model asks for a review,
+        # and the host renders, measures, decides what to adopt and when to stop.
+        #
+        # Iteration cap. The reason this is a cap rather than a budget is that the
+        # loop already stops when it stops helping; this is the backstop for "it
+        # keeps finding something new".
+        maxVisualIterations: 5
+        # Findings below this confidence are reported to the model but never
+        # auto-applied (SPEC §15.1 "低置信度问题不自动修复").
+        minVisualConfidenceForAutoFix: 0.8
+        # Consecutive rounds an unchanged finding may recur before the loop stops
+        # (SPEC §12.3 "同一问题两轮未改善则停止自动迭代").
+        stopOnRepeatedIssueCount: 2
+        # Vision reviewer route. Measured in the M2 probe: `deepseek-flash` accepts
+        # images (inputModalities ["text","image"]). The catalog also carries a
+        # text-only `deepseek-v4-flash`, which would silently omit the sheet.
+        visualReviewProvider: deepseek-official
+        visualReviewModel: deepseek-flash
+        # Token budget for one reviewer call. Measured: with the full reviewer prompt
+        # and a 2x2 sheet, this model spends ~11 000 tokens on reasoning BEFORE it emits
+        # any text, so a budget sized for the answer alone ends the stream with no text
+        # at all — which downstream looks exactly like "reviewed it, found nothing".
+        visualReviewMaxTokens: 24000
+        # Views in the standard plan, in reading order. Four is the measured
+        # balance: a 2x2 sheet survives the request pixel budget at roughly 1:1 per
+        # tile, while nine tiles fall below the source resolution and turn a partial
+        # occlusion into an invisible one (`runtime-audit.md` §7.2.3).
+        visualReviewViews:
+          - active-camera
+          - three-quarter
+          - top
+          - detail
+
+    # Browser-facing host half. M0 serves the settings-card document; the Web
+    # Client Slot half arrives in M4.
+    - id: deepblend-blender-ui
+      name: '@deepblend/dsh-blender-ui'
+      config:
+        serveRoute: true
+
+    # ── THE AGENT-PRESET PLANE'S DELIVERABLE ────────────────────────────────
+    #
+    # The sixteen model-visible tools belong to an AGENT PRESET, not to this
+    # composition (SPEC §4.3): registering them here would hand the Blender
+    # toolset to every session in the process. So the preset is not a row of
+    # tools — it is a directory under `<DSH_HOME>/.agent-presets/`, and
+    # `dsh plugin add` installs a package rather than writing a user's preset
+    # root.
+    #
+    # Without this row the plugin installs and HALF works: the workbench appears,
+    # the project store serves, and no session can render anything, because the
+    # model has no `blender_*` tool to call. The package this row mounts ships
+    # the preset and installs it, which is what makes the one-line install the
+    # whole install. `dsh-expert-orchestrator` is the same shape on the plugin
+    # list.
+    #
+    # It deploys when the profile composes, idempotently, into
+    # `<DSH_HOME>/.agent-presets/` only — never the root itself, never another
+    # preset — and a home it cannot write is logged rather than thrown, because a
+    # convenience copy must not take a deployment down. `deploy: false` leaves a
+    # preset root that an operator manages themselves untouched.
+    #
+    # The two paths are EMPTY on purpose, for the reason the first row's comment
+    # gives: a machine-dependent value belongs in the package that owns it, where
+    # it is ordinary Node code that can look at `DSH_HOME` and at its own
+    # location. `''` means "the default", and the default is derived once in
+    # `@deepblend/dsh-blender-preset/deploy`.
+    - id: deepblend-blender-preset
+      name: '@deepblend/dsh-blender-preset'
+      config:
+        deploy: true
+        # Empty means every preset the package ships: a preset added to the
+        # package then arrives without a composition change.
+        presets: []
+        # Empty means `<DSH_HOME>/.agent-presets`.
+        target: ''

package/lib/index.js

@@ -0,0 +1,29 @@
+/**
+ * @deepblend/dsh-blender-bundle
+ *
+ * This package is **patch-only**: it contributes no runtime plugin, no service
+ * and no tool of its own. Its entire contribution is `cordis.patch.yml`,
+ * declared through `dsh.bundle.patch` and composed by the profile boot before
+ * the profile's own patch layer.
+ *
+ * The module exists so the package is a well-formed, importable ESM package —
+ * an `exports` map with no `.` entry makes `require.resolve('@deepblend/dsh-blender-bundle')`
+ * fail, which breaks tooling that introspects a profile's bundle list.
+ *
+ * The rows it inserts are:
+ *   - `deepblend-blender-runtime` → `@deepblend/dsh-blender-provider-local`
+ *   - `deepblend-blender-host`    → `@deepblend/dsh-blender-host`
+ *   - `deepblend-blender-ui`      → `@deepblend/dsh-blender-ui`
+ */
+
+/** The bundle's patch file, relative to the package root. */
+export const PATCH_FILE = 'cordis.patch.yml'
+
+/** Row ids this bundle inserts, in composition order. */
+export const ROW_IDS = Object.freeze([
+  'deepblend-blender-runtime',
+  'deepblend-blender-host',
+  'deepblend-blender-ui',
+])
+
+export default { PATCH_FILE, ROW_IDS }

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@deepblend/dsh-blender-bundle",
+  "version": "0.1.0",
+  "description": "DeepBlend Studio Host Bundle: composes the Blender runtime provider, host facade and UI host half, with default configuration.",
+  "main": "lib/index.js",
+  "exports": {
+    ".": {
+      "default": "./lib/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "cordis.patch.yml",
+    "screenshots.json"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "dependencies": {
+    "@deepblend/dsh-blender-contracts": "0.1.0",
+    "@deepblend/dsh-blender-host": "0.1.0",
+    "@deepblend/dsh-blender-preset": "0.1.0",
+    "@deepblend/dsh-blender-provider-local": "0.1.0",
+    "@deepblend/dsh-blender-tool": "0.1.0",
+    "@deepblend/dsh-blender-ui": "0.1.0"
+  },
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pearjelly/deep-blend.git"
+  }
+}

package/screenshots.json

@@ -0,0 +1,5 @@
+[
+  "deepblend/docs/images/workbench-scene.png",
+  "deepblend/docs/images/render-contact-sheet.png",
+  "deepblend/docs/images/preview-compare.png"
+]