spine-parts 2.23.2 → 2.23.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/docs/AUTHORING.md CHANGED
@@ -820,6 +820,26 @@ strand order nor motion-space gaps.
820
820
  `PAINTING_EDGE_COVERAGE_TRANSFER` prints the pixel count and report filename.
821
821
  The report observes the existing allocation and leaves its raster writes intact.
822
822
 
823
+ Each evaluated alternate writes `painting_allocation.<encoded-set-name>.json`,
824
+ including an empty reading. `set`, `grid`, the source painting's SHA-256 and
825
+ `stage` qualify its native coordinates. `membership` is
826
+ `pre-filter-alternate-assembly`, the alternate evaluation before export
827
+ filtering. It excludes inherited base parts from that evaluation. Partial sets
828
+ list `inherited_parts` and `hidden_parts`; `output_assets` maps evaluated and
829
+ base part names to exported image filenames relative to the parts directory,
830
+ with inherited parts mapped to base images and hidden or filtered parts to null.
831
+ The CLI names each set and its report. An empty primary transfer membership does
832
+ not suppress an alternate reading. This is the meaning of primary absent with
833
+ alternate present here; the primary reading itself remains present under visible
834
+ projection.
835
+
836
+ On reuse, the primary report's `written_reports` list identifies owned alternate
837
+ reports for cleanup. Only those recorded paths are removed, and current
838
+ configured output paths are preserved. An older report without this list owns
839
+ no alternate report paths. A report path colliding with another output is
840
+ refused before emission with `PAINTING_ALLOCATION_UNAMBIGUOUS`.
841
+
842
+
823
843
  ### Residual front/back edges (`edge_residuals.json`, issue #999)
824
844
 
825
845
  Under `assemble.project: "visible"`, assemble writes `edge_residuals.json` beside
@@ -5289,6 +5309,7 @@ those settings. Changing a config seed alone cannot change a no-config run.
5289
5309
  | <a id="ASSEMBLE_TAKE_PLAN_ORDER"></a>`ASSEMBLE_TAKE_PLAN_ORDER` | supplied plan reverses an overlapping mixed-run pair: two-run full-layer head roles first, scalar depth within a role band (head-run and single-run rows use scalar depth); names the parts and support intersection | use the order drafted by `assemble --propose-plan`; fallback headwear follows the body and precedes the face, front hair follows the face; disjoint supports impose no plan-order constraint |
5290
5310
  | <a id="EDGE_PAIR_RESIDUAL"></a>`EDGE_PAIR_RESIDUAL` | report-only front/back residual candidates after visible edge composition, with pixel spans, boxes and coverage | read measured candidates and explicit skipped/unavailable reasons in `edge_residuals.json`. No pass/fail threshold is applied |
5291
5311
  | <a id="PAINTING_EDGE_COVERAGE_TRANSFER"></a>`PAINTING_EDGE_COVERAGE_TRANSFER` | accepted allocation clears legacy FRONT coverage into a BEHIND owner | read native rig membership in `painting_allocation.json`. Painted order and motion gaps require separate evidence |
5312
+ | <a id="PAINTING_ALLOCATION_UNAMBIGUOUS"></a>`PAINTING_ALLOCATION_UNAMBIGUOUS` | an alternate allocation report shares an output path | choose distinct output paths and set names |
5292
5313
  | <a id="ASSEMBLE_REGION_TAKE_REFERENCE_IMPLICIT"></a>`ASSEMBLE_REGION_TAKE_REFERENCE_IMPLICIT` | warning, `reference` is absent and the predicate uses `--source` | declare a painting reference and its PNG hash to keep the mask independent of projection-source changes |
5293
5314
  | <a id="ASSEMBLE_REGION_TAKE_REFERENCE"></a>`ASSEMBLE_REGION_TAKE_REFERENCE` | a declared region reference is unreadable | supply the declared PNG, with `source: true` or `painting` and its byte hash |
5294
5315
  | <a id="ASSEMBLE_REGION_TAKE_REFERENCE_MATCH"></a>`ASSEMBLE_REGION_TAKE_REFERENCE_MATCH` | a reference hash or painting dimensions differ | supply the declared PNG and preserve the source geometry |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "spine-parts",
3
- "version": "2.23.2",
3
+ "version": "2.23.3",
4
4
  "description": "AI-authored 2D character parts from one anime painting and its See-through layer decomposition: measured parts, weighted-mesh rig specs, verified through rig-c before anything is written. A CLI for agents that cannot see the image.",
5
5
  "type": "module",
6
6
  "bin": {
package/src/assemble.ts CHANGED
@@ -5,7 +5,7 @@ import { edgePairResiduals, type EdgeResidualReport } from './edgeresidual.ts';
5
5
  import type { SupportDomain } from './coincide.ts';
6
6
  import { type SeamRule } from './seamrule.ts';
7
7
  import { DEFAULT_GROUND, DEFAULT_PROJECT_RULE, type Ground, type ProjectRule } from './projectrule.ts';
8
- import { paintingEdges, type PaintingAllocationReading, type PaintingEdgeSkips } from './paintingedges.ts';
8
+ import { paintingEdges, type PaintingAllocationReading, type PaintingAllocationEvent, type PaintingEdgeSkips } from './paintingedges.ts';
9
9
  import { edgeLength } from './length.ts';
10
10
  import { materialSource, type MaterialSource, materialRows, polygonMaterialEdges, type MaterialRow, type MaterialEdge, type PlacedArt } from './cutmaterial.ts';
11
11
  import { unionTakenSources } from './takesource.ts';
@@ -304,6 +304,8 @@ export function singleRunPadRecord(single: boolean, sourceW: number, sourceH: nu
304
304
  }
305
305
 
306
306
  export interface AssembleInput {
307
+ /** Observe allocation decisions after guarding and restoration. */
308
+ allocationEvent?: (event: PaintingAllocationEvent) => void;
307
309
  /** Counterfactual before seeded takes, with whole-layer takes already applied. */
308
310
  regionTake?: { full: LayerSet; head: LayerSet; targets: string[] };
309
311
  /** Turn context for the exact part/carrier declarations, never an exemption flag. */
@@ -5878,6 +5880,7 @@ function assembleParts(input: AssembleInput, targets?: ReadonlySet<string>, befo
5878
5880
  })), lineage);
5879
5881
  const e = paintingEdges(canvases, srcr, {
5880
5882
  owner: receivers,
5883
+ allocationEvent: input.allocationEvent,
5881
5884
  painted: supportPainted,
5882
5885
  figure: visibleFigure,
5883
5886
  ...(input.declaredFigure === undefined ? {} : { declaredFigure: input.declaredFigure }),
package/src/build.ts CHANGED
@@ -6,7 +6,7 @@ import { SUPPORT_DOMAINS_FILE, writeSupportDomains } from './supportdomains.ts';
6
6
  import { COINCIDE_LINE, supportLines } from './coincide.ts';
7
7
  import { DEFAULT_SEAM_RULE } from './seamrule.ts';
8
8
  import { DEFAULT_PROJECT_RULE } from './projectrule.ts';
9
- import { EDGE_CONTRAST, PAINTING_ALLOCATION_FILE, PAINTING_EDGE_COVERAGE_TRANSFER } from './paintingedges.ts';
9
+ import { type PaintingAllocationReading, type PaintingAllocationEvent, EDGE_CONTRAST, PAINTING_ALLOCATION_FILE, PAINTING_EDGE_COVERAGE_TRANSFER } from './paintingedges.ts';
10
10
  import { SETUP_PAINTING_LINE, setupPaintingLines } from './setuppainting.ts';
11
11
  import { boundaryColourLines } from './boundarycolour.ts';
12
12
  import { writeMaterialSources } from './cutmaterialio.ts';
@@ -63,7 +63,7 @@ import { setFocusProblems } from './setfocus.ts';
63
63
  */
64
64
  import { createHash } from 'node:crypto';
65
65
  import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
66
- import { dirname, join, resolve } from 'node:path';
66
+ import { basename, dirname, join, resolve } from 'node:path';
67
67
  import { type AnimFrame, EncodeError, encodeApng, encodeIndexedApng, INDEXED_DEFAULTS } from './apng.ts';
68
68
  import { assemble, type AssembleResult, cutLines, type ExcludedCount, excludedLines, setExclusions, islandLines, setIslandSources, type IslandCount, hiddenLines, SINGLE_RUN_FACE_TAGS, singleRunHeadBox, softOcclusionLine, driftLine, limbLines, FIGURE_MASK_FILE, figuresLine, groundWarning, holeKindsLine, holeLines, measurePinholes, measureRecomposite, pinholeProblems, pinholesLine, type ProjectRule, recomposite, recompositeRecord, scenePhrase, type SeamRule, sourceInRig, stageFields, uncoveredLine } from './assemble.ts';
69
69
  import { allocationClause, type Reducer, stageBClause, unboundedClause } from './automesh.ts';
@@ -170,6 +170,8 @@ export interface AlternateCliInput {
170
170
  }
171
171
 
172
172
  export interface AssembleStageInput {
173
+ /** A null set identifies the primary assembly evaluation. */
174
+ allocationEvent?: (event: PaintingAllocationEvent, set: string | null) => void;
173
175
  /** Write source-edge evidence only when cut_material is explicitly declared. */
174
176
  requirements?: string;
175
177
  source: string;
@@ -366,7 +368,7 @@ export function assembleStage(input: AssembleStageInput, outs: AssembleOutputs,
366
368
  const declaredFigure = figureSupport === undefined ? undefined : { width: Math.trunc(src.width * fields.rigScale), height: Math.trunc(src.height * fields.rigScale), data: figureSupport };
367
369
  const under = readUnders(input.config, fields.cuts);
368
370
  const caps = fields.limbs === undefined ? undefined : readCaps(input.config, fields.limbs);
369
- const result = assemble({ source: src, full: runs.full, head: runs.head, depth: cfg.depth, depthBase: dirname(resolve(input.config)), ...fields, under, ...(declaredFigure === undefined ? {} : { declaredFigure }),
371
+ const result = assemble({ allocationEvent: input.allocationEvent === undefined ? undefined : event => input.allocationEvent!(event, null), source: src, full: runs.full, head: runs.head, depth: cfg.depth, depthBase: dirname(resolve(input.config)), ...fields, under, ...(declaredFigure === undefined ? {} : { declaredFigure }),
370
372
  ...((cfg.assemble.take ?? []).some(t => 'part' in t) ? { regionTake: { full: takenRuns.full, head: takenRuns.head, targets: (cfg.assemble.take ?? []).flatMap(t => 'part' in t ? [t.part] : []) } } : {}), ...(caps === undefined ? {} : { caps }), seamRule: seam, projectRule: project });
371
373
 
372
374
  // Issue #454: alternate painting sets, assembled before any file is written.
@@ -427,6 +429,7 @@ export function assembleStage(input: AssembleStageInput, outs: AssembleOutputs,
427
429
  }
428
430
 
429
431
  const altProblems: Problem[] = [];
432
+ const allocationReports: Array<{ file: string; report: { set: string; coverageTransfers: PaintingAllocationReading['coverageTransfers'] } & Record<string, unknown> }> = [];
430
433
  const altBuilt: Array<{ record: AlternatePartsRecord; images: Array<{ name: string; image: Raster }>; excluded: ExcludedCount[]; islands: IslandCount[]; splits: SplitCount[]; capSplits: SplitCount[]; depthClamps: AssembleResult['depthClamps'] }> = [];
431
434
  const baseSlots = result.parts.parts.map((p) => p.name);
432
435
  // Issue #664: each limb segment part with a declared front slot -> the part its front slot follows.
@@ -704,6 +707,7 @@ export function assembleStage(input: AssembleStageInput, outs: AssembleOutputs,
704
707
  let altRes: ReturnType<typeof assemble>;
705
708
  try {
706
709
  altRes = assemble({
710
+ allocationEvent: input.allocationEvent === undefined ? undefined : event => input.allocationEvent!(event, alt.name),
707
711
  source: altSrc,
708
712
  depth: cfg.depth, depthBase: configDir,
709
713
  limbUnderCover: alt.parts !== undefined && input.setCover !== 'painting',
@@ -772,6 +776,25 @@ export function assembleStage(input: AssembleStageInput, outs: AssembleOutputs,
772
776
  const altCan = recomposite(fullSetPlaced, rW, rH);
773
777
  altRecomposite = recompositeRecord(measureRecomposite(altCan, altSrcRig, fullSetPlaced));
774
778
  }
779
+ const alternateAllocation = altRes.paintingEdges?.allocation;
780
+ if (alternateAllocation !== undefined) {
781
+ allocationReports.push({
782
+ file: `painting_allocation.${encodeURIComponent(alt.name)}.json`,
783
+ report: {
784
+ spec: 'rig-parts-painting-allocation/1', code: PAINTING_EDGE_COVERAGE_TRANSFER,
785
+ set: alt.name, grid: altRes.parts.rig_size,
786
+ source: { painting_sha256: createHash('sha256').update(readFileSync(alt.source)).digest('hex') },
787
+ stage: 'paintingEdges after piece guarding and restoration',
788
+ membership: 'pre-filter-alternate-assembly',
789
+ output_assets: [...new Set([...altRes.parts.parts.map(part => part.name), ...baseSlots])].map(name => ({ part: name,
790
+ image: hidesSet.has(name) ? null : keptRecords.some(record => record.name === name)
791
+ ? `${alt.name}_${name}.png` : !coveredSet.has(name) ? `${name}.png` : null })),
792
+ inherited_parts: baseSlots.filter(name => !coveredSet.has(name) && !hidesSet.has(name)),
793
+ hidden_parts: [...hidesSet],
794
+ ...alternateAllocation,
795
+ },
796
+ });
797
+ }
775
798
  altBuilt.push({
776
799
  record: {
777
800
  name: alt.name,
@@ -821,6 +844,23 @@ export function assembleStage(input: AssembleStageInput, outs: AssembleOutputs,
821
844
  assetIndices.set(file, index);
822
845
  }
823
846
  });
847
+ const outputFiles = new Set([
848
+ outs.partsJson, outs.recomposite, outs.errorMap,
849
+ join(dirname(outs.partsJson), PAINTING_ALLOCATION_FILE),
850
+ join(dirname(outs.partsJson), PAINTING_IN_RIG_FILE),
851
+ join(dirname(outs.partsJson), SUPPORT_DOMAINS_FILE),
852
+ join(dirname(outs.partsJson), CUT_MATERIAL_SOURCES),
853
+ join(dirname(outs.partsJson), STAGE_MAP_FILE),
854
+ join(dirname(outs.partsJson), EDGE_RESIDUAL_FILE),
855
+ ...emittedAssets.map(file => join(outs.partsDir, file)),
856
+ ].map(file => resolve(file)));
857
+ for (const { file, report } of allocationReports) {
858
+ const path = resolve(dirname(outs.partsJson), file);
859
+ if (outputFiles.has(path)) altProblems.push({ code: 'PAINTING_ALLOCATION_UNAMBIGUOUS',
860
+ object: `alternate set "${report.set}" report "${file}"`,
861
+ detail: 'shares an output path with another artifact; choose distinct output paths and set names' });
862
+ outputFiles.add(path);
863
+ }
824
864
  // Issue #944: under pinholes.required, every pinhole of the base set's flat parts stack is refused by name, with the
825
865
  // alternate sets' refusals, before anything is written.
826
866
  const pinholes = pinholesAsked ? measurePinholes(sourceInRig(src, result.parts.rig_size[0], result.parts.rig_size[1]), result.images) : null;
@@ -830,6 +870,23 @@ export function assembleStage(input: AssembleStageInput, outs: AssembleOutputs,
830
870
  result.parts.alternates = altBuilt.map((b) => b.record);
831
871
  }
832
872
 
873
+ const allocationPath = join(dirname(outs.partsJson), PAINTING_ALLOCATION_FILE);
874
+ let previousAllocationFiles: string[] = [];
875
+ if (existsSync(allocationPath)) {
876
+ try {
877
+ const previous: unknown = JSON.parse(readFileSync(allocationPath, 'utf8'));
878
+ if (previous !== null && typeof previous === 'object' && 'spec' in previous &&
879
+ previous.spec === 'rig-parts-painting-allocation/1' && 'written_reports' in previous &&
880
+ Array.isArray(previous.written_reports)) {
881
+ previousAllocationFiles = previous.written_reports.filter((file): file is string =>
882
+ typeof file === 'string' && file.startsWith('painting_allocation.') &&
883
+ file.endsWith('.json') && basename(file) === file);
884
+ }
885
+ } catch (error) {
886
+ if (!(error instanceof SyntaxError)) throw error;
887
+ }
888
+ }
889
+
833
890
  // Emit only after green: every refusal above has already thrown.
834
891
  mkdirSync(outs.partsDir, { recursive: true });
835
892
  mkdirSync(dirname(outs.partsJson), { recursive: true });
@@ -846,13 +903,23 @@ export function assembleStage(input: AssembleStageInput, outs: AssembleOutputs,
846
903
  const residualPath = join(dirname(outs.partsJson), EDGE_RESIDUAL_FILE);
847
904
  if (result.edgeResiduals === undefined) rmSync(residualPath, { force: true });
848
905
  else writeFileSync(residualPath, JSON.stringify(result.edgeResiduals, null, 2) + '\n');
849
- const allocationPath = join(dirname(outs.partsJson), PAINTING_ALLOCATION_FILE);
850
906
  const allocation = result.paintingEdges?.allocation;
851
907
  if (allocation === undefined) rmSync(allocationPath, { force: true });
852
908
  else writeFileSync(allocationPath, JSON.stringify({ spec: 'rig-parts-painting-allocation/1',
853
909
  code: PAINTING_EDGE_COVERAGE_TRANSFER,
854
910
  stage: 'paintingEdges after piece guarding and restoration', grid: result.parts.rig_size,
855
- ...allocation }, null, 2) + '\n');
911
+ ...allocation, written_reports: allocationReports.map(report => report.file) }, null, 2) + '\n');
912
+ const currentAllocationFiles = new Set(allocationReports.map(report => report.file));
913
+ for (const file of previousAllocationFiles) {
914
+ if (!currentAllocationFiles.has(file) && !outputFiles.has(resolve(dirname(outs.partsJson), file))) {
915
+ rmSync(join(dirname(outs.partsJson), file), { force: true });
916
+ }
917
+ }
918
+ for (const { file, report } of allocationReports) {
919
+ writeFileSync(join(dirname(outs.partsJson), file), JSON.stringify(report, null, 2) + '\n');
920
+ const count = report.coverageTransfers.reduce((n, row) => n + row.pixels.count, 0);
921
+ log(`${PAINTING_EDGE_COVERAGE_TRANSFER}: set "${report.set}" ${count} native rig px; membership in ${file}`);
922
+ }
856
923
  for (const { record, image, depthImage } of result.images) {
857
924
  writePng(join(outs.partsDir, `${record.name}.png`), image);
858
925
  if (depthImage !== undefined && record.depth !== undefined) writePng(join(outs.partsDir, record.depth.image), depthImage);
@@ -193,7 +193,20 @@ export interface PaintingAllocationReading {
193
193
  }>;
194
194
  }
195
195
 
196
+ /** Allocation status after piece guarding, before transfer membership is collected. */
197
+ export interface PaintingAllocationEvent {
198
+ readonly p: number;
199
+ readonly front: number;
200
+ readonly behind: number;
201
+ readonly target: number;
202
+ readonly affected: readonly number[];
203
+ readonly status: string;
204
+ readonly reason: string;
205
+ }
206
+
196
207
  export interface PaintingEdgeOptions {
208
+ /** Observes detached event values after restoration, without changing allocation. */
209
+ allocationEvent?: (event: PaintingAllocationEvent) => void;
197
210
  /** Named supplier and explicit receiver contract, frozen before the edge pass. */
198
211
  owner?: PaintingReceivers;
199
212
  /**
@@ -842,6 +855,7 @@ function applyPaintingEdges(
842
855
  for (const p of writes.keys()) options.written?.(i, p);
843
856
  });
844
857
  for (const [p, front] of restore) if (!planned[front].has(p)) options.written?.(front, p);
858
+ for (const event of events) options.allocationEvent?.({ ...event, affected: [...event.affected] });
845
859
  // The legacy FRONT surface was moved to an accepted BEHIND owner. Read the
846
860
  // applied output, including restoration: a held clear is never a transfer.
847
861
  if (reading !== undefined && allocation !== undefined && existing !== undefined) {