@rig-c/core 2.68.0 → 2.69.0

package/README.md

@@ -186,6 +186,16 @@ of them: it reads whatever frames you point it at, so it runs from the installed
 package on pictures of your own — which is what *Where to go next* below tells you
 to do with it, and it is the one instrument here that can see a wrong animation.
 
+Programmatic checked consumers can import `rig-c/render-shared`: the official
+candidate chooser (`loadCandidate`, `throughPoser`), setup and animation samplers
+(`sampleSetupPose`, `sampleAnimation`) and raster reads (`pageFor`, `projector`,
+`rasterisePiece`, `renderFrame`), with their argument/result types and named
+failures. It loads without the optional Spine runtime; a Spine input requires
+explicitly loading `rig-c/render`, whose eager runtime dependency is unchanged.
+The promised scope and planned first minor release are in
+[RELEASING.md, The import surface](https://github.com/rig-c/core/blob/main/RELEASING.md#the-import-surface);
+[AUTHORING §0.5](docs/AUTHORING.md#05-reading-a-build-from-code) shows the call chain.
+
 ### Install it into your agent
 
 The guides under [Documentation](#documentation) also ship as

package/docs/AUTHORING.md

@@ -1617,6 +1617,68 @@ written`, followed by `rigc repack: nothing was written to <out>; the work direc
 
 ---
 
+### 0.5 Reading a build from code
+
+The named `rig-c/render-shared` entry promises the official renderer reads for
+checked consumers (issue #1561). It is planned for the next minor, 2.69.0; wait
+for the measured release before using `>=2.69.0 <3.0.0`. It requires Bun and the
+candidate's real files, but imports no optional Spine runtime. The existing
+`rig-c/render` entry still eagerly imports that runtime.
+
+```ts
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import {
+  loadCandidate, throughPoser, sampleSetupPose, sampleAnimation,
+  pageFor, projector, rasterisePiece, renderFrame,
+  type Viewport,
+} from 'rig-c/render-shared';
+
+const dir = 'build';
+const skeleton = join(dir, 'skeleton.json');
+const atlas = join(dir, 'skeleton.atlas');
+const candidate = loadCandidate({
+  skeletonText: readFileSync(skeleton, 'utf8'),
+  atlasText: readFileSync(atlas, 'utf8'),
+  atlasDir: dir, label: skeleton,
+}, { skeleton, atlas }, undefined);
+const read = throughPoser(candidate.choice, (poser, roster) => ({
+  setup: sampleSetupPose(poser, { bones: true, geometry: true })[0],
+  frames: sampleAnimation(poser, 'wave', 12),
+  skins: roster.skins,
+}));
+// The consumer supplies the world box and pixel grid it intends to measure.
+const viewport: Viewport = {
+  minX: 0, minY: 0, maxX: 256, maxY: 256,
+  scale: 1, width: 256, height: 256,
+};
+const project = projector(viewport);
+for (const piece of read.value.setup.pieces) {
+  rasterisePiece(pageFor(candidate.pages, piece), piece, project, viewport,
+    (x, y, r, g, b, a) => { /* read each covered sample */ });
+}
+const image = renderFrame(read.value.setup, candidate.pages, viewport, [0, 0, 0, 0]);
+```
+
+The animation name and viewport above belong to the consumer; the loader does
+not invent them. The chooser checks the model document beside the skeleton,
+its `spine.sha256`, atlas placement, page files and bone/slot/animation rosters.
+A /3 document can be loaded with `atlasText: null` when its atlas is absent.
+`throughPoser` returns `poser` and `note` with its value. Keep its callback free
+of writes: an explicitly registered runtime fallback can rerun it.
+
+The entry also exports the original `CandidateAtlasError` (missing required
+atlas), `CandidatePairError` (unloadable pair or missing page),
+`SpineRuntimeError` (input needs an unregistered or unusable Spine side),
+`PoserChoiceError` (a forced-core pose refusal), `SlotSubsetError` (invalid
+slot subset) and `CoreInputError` (core input/pose refusal). The chooser's
+mismatch reason remains in the refusal: no silent substitute is selected by
+this entry. Unknown animation and missing `pageFor` page are `Error`s naming
+the requested name and available names. A forced-core flag keeps the existing
+deferred choice check; it alone does not prove `candidate.choice.core` exists.
+To use a Spine export or `forced: 'spine'`, install the runtime and explicitly
+import `rig-c/render` first; importing `render-shared` never registers it.
+
 ## 1. The two files
 
 ### 1.1 A complete minimal rig spec

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rig-c/core",
-  "version": "2.68.0",
+  "version": "2.69.0",
   "description": "AI-authored 2D rigging and animation, verified before it is written. rigc compiles a rig spec into skeleton data in the Spine 4.3 format, gates it with named assertions held to a spine-core round trip's verdicts, and emits nothing that fails. Ships as an agent skill.",
   "type": "module",
   "bin": {
@@ -11,6 +11,7 @@
     "./font5x7": "./tools/font5x7.ts",
     "./transform": "./src/transform.ts",
     "./render": "./src/render.ts",
+    "./render-shared": "./src/render_read.ts",
     "./png": "./src/png.ts",
     "./compile": "./src/compile.ts",
     "./rig": "./src/rig.ts",

package/src/render_read.ts

@@ -0,0 +1,55 @@
+/**
+ * The promised renderer reads for checked consumers (issue #1561).
+ *
+ * This entry registers no Spine side. Rigc builds use the official candidate
+ * chooser and core poser; inputs needing Spine are refused by SpineRuntimeError
+ * unless the consumer has explicitly loaded rig-c/render. That entry keeps its
+ * eager runtime import and registers the same implementation this seam uses.
+ * Only the agreed reads, their types and their existing failure classes belong
+ * here. The broader implementation module is not the public contract.
+ */
+export {
+  loadCandidate,
+  throughPoser,
+  sampleAnimation,
+  sampleSetupPose,
+  pageFor,
+  projector,
+  rasterisePiece,
+  renderFrame,
+  CandidateAtlasError,
+  CandidatePairError,
+  PoserChoiceError,
+  SlotSubsetError,
+} from './render_shared.ts';
+export { SpineRuntimeError } from './spine_side.ts';
+export { CoreInputError } from './core/index.ts';
+export type {
+  Candidate,
+  SkeletonFacts,
+  PoserChoice,
+  PoserName,
+  MakeCorePoser,
+  Poser,
+  Posed,
+  PoseSource,
+  PoseOptions,
+  DrawOptions,
+  SkinRoster,
+  SlotSubset,
+  Frame,
+  BoneSnapshot,
+  AttachmentPose,
+  AttachmentRest,
+  Piece,
+  PieceCommon,
+  PieceTexture,
+  UvWindow,
+  Quad,
+  Mesh,
+  ClipSource,
+  Viewport,
+  EmitPixel,
+} from './render_shared.ts';
+export type { Plate, RGBA } from '../tools/plate.ts';
+export type { EnvironmentStep, EnvironmentChange } from './environment.ts';