Model - Share#

API reference for src/core/share, src/schema/share on @huukhanhnguyen/model, reachable from ..

See the Guide for the ModelJSON / evaluate pipeline.

API reference#

Signatures are generated from the live package .d.ts - not hand-written.

extractShared#

function

Deep-copy the record id of type out of doc, plus everything it transitively references. Null when the doc has no such record. Broken references inside the source are skipped (copy what exists — fail-soft).

extractShared(doc: ModelJSON, type: ShareType, id: string): ShareBundle | null

installModel#

function

Install a catalog model into lanes as ONE new components[] entry — the "install from library" law replacing loadModel/placeModel entirely (see this module's doc). sourceDoc is the already-resolved (validated) document; proposedKey names the new component (renamed on a key conflict, same as every other lane mergeShared plans). The source's own components[] entries copy alongside it (their placeComponent refs rewritten by the ordinary rename pass); its parameters/operations become the new component's own parameters/operations — animation fields travel with parameters unchanged (plain JSON, nothing special to carry), and url-method parameters (attached fonts/images) travel the same way: the folded component's own parameters lane is the only "asset lane" an install needs. A luminaire needs no special case: its emitting entity rides in objects[] like any other object. settings.units is NOT converted — internal length is always mm; authored numeric args are mm regardless of the source's display unit (units is display-only). Deliberately NOT copied: tables/views/ sheets/cameras — install brings the geometry definition, not the paperwork. Throws if the source has no objects[] content (a component's operations can't be empty — schema law). Returns the installed key (post-rename).

installModel(lanes: ShareLanes, sourceDoc: ModelJSON, proposedKey: string): { key: string; }

mergeShared#

function

Copy bundle into lanes. Identical same-id records are REUSED (a re-copy is a no-op); conflicting ones are renamed with every internal reference rewritten. Returns the root record's FINAL id in the target.

ponytail: when ANY rename occurs in a REFERENCED lane (textures/ components), the whole plan re-runs with reuse disabled — a reused-but- rewritten dependency would otherwise silently recombine incoming content with the target's same-named records. Mixed partial-conflict copies duplicate a few identical records instead; the common cases (clean target, exact re-copy) keep full dedup. Materials/layers are referenced by nothing, so their renames never trigger the re-plan.

mergeShared(lanes: ShareLanes, bundle: ShareBundle): { id: string; }

SHARE_TYPES#

const

Shareable lane kinds — SSOT lives in schema (SPEC §5.3).

const SHARE_TYPES: readonly ["material", "texture", "layer"]

ShareBundle#

type

type ShareBundle
// = {
    /** Lane of the bundle's ROOT record. The public share types never
     *  include a bare component — a single component is not a share unit
     *  (building blocks move as a WHOLE model); "component" appears only on
     *  `installModel`'s internal whole-model bundle below. */
    type: ShareType | "component";
    /** The root record's id (name/key by lane) in the SOURCE doc. */
    id: string;
    /** Material nodes (method "material") — identity is the evaluated/literal name. */
    materials: (Operation | Container)[];
    textures: Chain[];
    components: Component[];
    /** Layer nodes (method "layer") — identity is the evaluated/literal name. */
    layers: (Operation | Container)[];
}

ShareLanes#

type

The target document's shareable lanes (a ModelScope satisfies this).

type ShareLanes
// = {
    materials: (Operation | Container)[];
    textures: Chain[];
    components: Component[];
    layers: (Operation | Container)[];
}

ShareType#

type

type ShareType
// = (typeof SHARE_TYPES)[number]