@code3d/core 0.0.1-alpha.0 → 0.0.1-alpha.11

package/docs/values.md

@@ -0,0 +1,119 @@
+---
+title: Model values and measurements
+description: Understand immutable models, geometry measurements and composition.
+sidebar:
+  order: 2
+---
+
+## Model values and coordinates
+
+Operations produce new model values. Building another result must not change an
+already-observable model's geometry, material, topology, or relations.
+
+In `part.relate(self => ...)`, the callback parameter represents the new value.
+`part` and any aliases or element references selected from it still refer to the
+original value. Each constraint must involve the callback value.
+
+A model's local geometry and its placement in a composition are separate.
+`relate()` records how a part is placed when composed with other parts; observing
+that part alone shows its local geometry. `originOffset()` changes geometry
+coordinates without changing the shape. Position arrays use `[x, y, z]`; scalar
+angles use degrees. Read [local coordinates](local-coordinates.md)
+and [relations](relations.mdx) before mixing
+origin changes, alignment, and rotation.
+
+Constraints express `on` and `align` only. Put relative `offset` and `rotate`
+transformations in the `relate` array after the constraints. Zero values add no
+centering or orientation condition; use point or axis alignment to center a part.
+The App's gizmos edit or insert independent array entries.
+
+Choose a
+center with `pivot([x,y,z])`, self topology with `pivotVertex(id)`/`axisEdge(id)`,
+or references with `pivotPoint(pointRef)`/`axisLine(lineRef)`; finish each selector
+with `rotate`. Point rotations retain self XYZ axes, including external centers. Consecutive constraints solve jointly; transformations
+then act on that result in order. A later constraint starts a new segment using
+the preceding pose. Independent offsets use fixed composition axes, and rotations
+default to self's current origin. Each completed transformation is one array item,
+for example `[offset(0, 8, 0), rotate(0, 25, 0)]`. Only pivot/axis selections
+chain into `rotate`; completed transformations cannot chain into another operation.
+Keep a selected reference while moving it with
+`pivotVertex(id).pivotOffset(dx, dy, dz).rotate(x, y, z)` or
+`axisLine(axis).axisOffset(dx, dy, dz).rotate(angle)`. Point offsets use self local
+axes; axis offsets use the selected axis frame and preserve its direction.
+Each selector accepts one matching offset, followed by `rotate`.
+See the [transformation example](../../app/examples/constraints/transformations.ts)
+and [placement guide](relations.mdx#transform-a-joint-result).
+
+Build readable models from named intermediate values and public operations. A
+profile followed by extrusion, or solids combined with Boolean operations,
+keeps the construction understandable and editable by both people and agents.
+
+## Measure geometry for another part
+
+`distance(a, b, axis?)` measures models, finite topology, bounds or point anchors
+in their solved placement and returns a normal non-negative number. Omit the axis
+for shortest geometric distance; supply `x`, `y`, `z`, a direction vector or a
+straight edge/axis reference for the gap between projected intervals. Overlap
+returns zero. Existing relations are resolved on demand, before any group is
+needed; subsequent relations do not update the number.
+
+See the [measurement reference](api.md#measurements)
+and the [fitted beam example](../../app/examples/operations/distance.ts). They cover
+finite geometry, nested occurrences, axis frames and source-order dependencies.
+
+## Geometry measurements
+
+`model.bounds(relativeTo?)` returns readonly `minimum`, `maximum` and `size`
+XYZ vectors for tight finite geometry bounds. By default it uses the model's
+own local frame. An explicit reference includes solved placement and nested
+member occurrences in that reference's frame. Empty groups have no finite
+bounds; a source occurring more than once in the reference is ambiguous.
+
+`model.position(relativeTo)` returns the model origin in the explicit reference's
+local frame. A model's origin in its own frame is always `[0, 0, 0]`, including
+point models whose geometry may be offset from that origin. Neither query
+changes the model or its placement. These methods are available on every model
+kind, including groups. As model members, `bounds` and `position` are reserved
+names and cannot be used as exposed element names.
+
+```ts
+import {box, group, offset} from '@code3d/core';
+
+const base = box(20, 4, 20);
+const part = box(8, 12, 4).relate(self => [self.on(base.up), offset(20, 0, 0)]);
+const size = part.bounds().size; // [8, 12, 4]
+const origin = part.position(base); // [20, 8, 0]
+const minimum = part.bounds(base).minimum; // [16, 2, -2]
+export default group([base, part]);
+```
+
+Dimension-based primitives and numeric modeling methods retain required TypeScript
+signatures while providing runtime defaults for omitted or `undefined` values.
+Rotations and displacements default to zero, scaling to one, extrusion distance
+to ten, and fillet radius, chamfer distance and shell thickness to one. Relation
+rotation selectors use the same angle defaults; `pivot()` defaults to local zero.
+Explicit invalid values retain their normal errors. These defaults work in
+ordinary JavaScript execution as well as App previews.
+
+The App displays defaults as placeholders without inserting source arguments.
+Committing a spatial drag fills all remaining omitted defaults in that operation;
+for example, dragging the X ring of `rotate()` writes `rotate(angle, 0, 0)`. The
+edit and completion share one undo step. Use explicit dimensions in finished
+models; the [reference](api.md#runtime-defaults-while-editing)
+lists the actual defaults.
+
+Topology capabilities follow dimension: vertices expose vertex selection, edges
+add edge selection, and faces and solids add surface selection. Only solids
+provide `fillet`, `chamfer`, and `shell`. Groups compose values and support
+relations, exposed elements, and materials without pretending to be geometry.
+
+Groups are model values and can be nested directly with `group([inner, other])`,
+including in mixed `Model[]` collections. Nesting preserves each group's hierarchy;
+`expose()` adds named references when callers need to address members.
+
+A topology ID belongs to its owning model and element kind. It is a number or a
+flat numeric path, such as `.edge([1, 3])`. Local edits (`fillet`, `chamfer`, `shell`)
+preserve one-to-one IDs and allocate fresh IDs for new elements without reusing
+retired numbers. Loft, extrusion and Booleans prefix inherited IDs by input;
+transforms preserve complete paths. Inspect the result after topology changes
+instead of assuming IDs from a different model still apply.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@code3d/core",
-  "version": "0.0.1-alpha.0",
+  "version": "0.0.1-alpha.11",
   "publishConfig": {
     "access": "public"
   },
@@ -8,10 +8,11 @@
   "author": "vilicvane",
   "type": "module",
   "scripts": {
-    "prepack": "node ../../scripts/package-license.mjs",
-    "test": "node ../../node_modules/typescript/bin/tsc --build src/library/tsconfig.json src/node/tsconfig.json src/tooling/tsconfig.json && npm run test:types && npm run test:run",
-    "test:run": "node --test \"test/*.test.{mjs,ts}\"",
-    "test:types": "node ../../node_modules/typescript/bin/tsc --noEmit -p test/tsconfig.json"
+    "prepack": "npm run build",
+    "test": "npm run build && npm run test:types && npm run test:run",
+    "test:run": "node --import ../../test/source-loader.mjs --test --test-concurrency=1 \"test/*.test.{mjs,ts}\"",
+    "test:types": "node ../../node_modules/typescript/bin/tsc --noEmit -p test/tsconfig.json",
+    "build": "node ../../scripts/build-packages.mjs @code3d/core"
   },
   "exports": {
     ".": {
@@ -39,15 +40,27 @@
     "bld",
     "THIRD_PARTY.md",
     "README.md",
-    "src"
+    "src",
+    "docs"
   ],
   "dependencies": {
     "@code3d/opencascade": "0.0.1-alpha.0",
-    "@ctrl/tinycolor": "^4.2.0",
     "@salusoft89/planegcs": "1.2.0",
+    "@types/emscripten": "1.41.5",
     "@types/three": "^0.185.4",
+    "harfbuzzjs": "1.6.1",
+    "manifold-3d": "3.0.1",
     "replicad": "^1.0.1",
     "replicad-opencascadejs": "1.0.0",
     "three": "^0.185.1"
+  },
+  "devDependencies": {
+    "@ctrl/tinycolor": "^4.2.0",
+    "flo-boolean": "5.0.8"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vilicvane/code3d.git",
+    "directory": "packages/core"
   }
 }

package/src/library/bound-solver.ts

@@ -7,17 +7,56 @@ import {
   origin,
   rotateVector,
   rotation,
-  transformsAreEquivalent,
   type Quaternion,
   type RigidTransform,
   type Vec3,
 } from './spatial.js';
 
 export type Bounds = readonly [minimum: Vec3, maximum: Vec3];
-export type BodyRotation =
-  | Readonly<{local: RigidTransform}>
-  | Readonly<{axis: RigidTransform; body: number; angle: number}>;
+export type ExternalRotation =
+  | Readonly<{axis: RigidTransform; body: number; angle: number}>
+  | Readonly<{
+      point: Vec3;
+      body: number;
+      rotation: Quaternion;
+      displacement: Vec3;
+    }>;
+export type BodyRotation = Readonly<{local: RigidTransform}> | ExternalRotation;
 
+/** External center relative to its owning body; point references retain self's axes. */
+export function externalRotationFrame(
+  action: ExternalRotation,
+  self: Quaternion,
+  reference: Quaternion,
+  inverse = false,
+): {center: Vec3; quaternion: Quaternion} {
+  if ('axis' in action) {
+    const axis = composeTransforms(rotation(reference), action.axis);
+    return {
+      center: axis.position,
+      quaternion: axisRotation(axis, inverse ? -action.angle : action.angle)
+        .quaternion,
+    };
+  }
+  const local = inverse
+    ? invertTransform(rotation(action.rotation))
+    : rotation(action.rotation);
+  const before = inverse
+    ? composeTransforms(rotation(self), local)
+    : rotation(self);
+  return {
+    center: addVectors(
+      rotateVector(action.point, reference),
+      rotateVector(action.displacement, before.quaternion),
+    ),
+    quaternion: composeTransforms(
+      composeTransforms(before, local),
+      invertTransform(before),
+    ).quaternion,
+  };
+}
+
+export type BodyAction = BodyRotation | Readonly<{offset: Vec3}>;
 export type BodyRelation = Readonly<{
   id: string;
   source: Readonly<{
@@ -26,11 +65,16 @@ export type BodyRelation = Readonly<{
     bounds: (orientation: Quaternion) => Bounds;
   }>;
   target: Readonly<{body: number; transform: RigidTransform; facing: 1 | -1}>;
-  offset: Vec3 | undefined;
-  rotations: readonly BodyRotation[];
 }>;
 
-export type Body = Readonly<{name: string; relations: readonly BodyRelation[]}>;
+export type Body = Readonly<{
+  name: string;
+  relations: readonly BodyRelation[];
+  /** Pose inherited from the preceding placement segment. */
+  initial?: RigidTransform;
+  /** Independent actions apply after the joint constraint solution. */
+  transformations?: readonly BodyAction[];
+}>;
 type AffinePoint = {constant: Vec3; columns: Vec3[]};
 type AffinePose = {position: AffinePoint; quaternion: Quaternion};
 type Equation = {id: string; coefficients: number[]; value: number};
@@ -74,37 +118,21 @@ export function solveBodies(
         'Cyclic external rotation axes cannot determine an authored orientation.',
       );
     visiting.add(index);
-    const candidates = bodies[index].relations
-      .filter(r => r.rotations.length)
-      .map(relation => {
-        let pose = identityRigidTransform;
-        for (const action of relation.rotations) {
-          pose =
-            'local' in action
-              ? composeTransforms(pose, action.local)
-              : composeTransforms(
-                  axisRotation(
-                    composeTransforms(seed(action.body), action.axis),
-                    action.angle,
-                  ),
-                  pose,
-                );
-        }
-        return pose;
-      });
-    const pose = candidates[0] ?? identityRigidTransform;
-    if (
-      candidates.some(
-        candidate =>
-          !transformsAreEquivalent(
-            rotation(candidate.quaternion),
-            rotation(pose.quaternion),
-          ),
-      )
-    ) {
-      throw new Error(
-        `Conflicting explicit rotations for ${bodies[index].name}.`,
-      );
+    let pose = bodies[index].initial ?? identityRigidTransform;
+    for (const action of bodies[index].transformations ?? []) {
+      if ('offset' in action) continue;
+      pose =
+        'local' in action
+          ? composeTransforms(pose, action.local)
+          : 'point' in action
+            ? composeTransforms(pose, rotation(action.rotation))
+            : composeTransforms(
+                axisRotation(
+                  composeTransforms(seed(action.body), action.axis),
+                  action.angle,
+                ),
+                pose,
+              );
     }
     visiting.delete(index);
     seeds.set(index, pose);
@@ -120,19 +148,18 @@ export function solveBodies(
     const known = positioned.get(index);
     if (known) return known;
     let pose: AffinePose = {
-      quaternion: identityRigidTransform.quaternion,
+      quaternion: (bodies[index].initial ?? identityRigidTransform).quaternion,
       position: {
-        constant: origin,
+        constant: (bodies[index].initial ?? identityRigidTransform).position,
         columns: variables.flatMap(body =>
           axes.map(axis => (body === index ? axis : origin)),
         ),
       },
     };
-    const actions =
-      bodies[index].relations.find(relation => relation.rotations.length)
-        ?.rotations ?? [];
-    for (const action of actions) {
-      if ('local' in action) {
+    for (const action of bodies[index].transformations ?? []) {
+      if ('offset' in action) {
+        pose = {...pose, position: shiftPoint(pose.position, action.offset)};
+      } else if ('local' in action) {
         pose = {
           position: shiftPoint(
             pose.position,
@@ -145,12 +172,12 @@ export function solveBodies(
         };
       } else {
         const axisPose = positionBody(action.body);
-        const axis = composeTransforms(
-          rotation(axisPose.quaternion),
-          action.axis,
+        const {center, quaternion: q} = externalRotationFrame(
+          action,
+          pose.quaternion,
+          axisPose.quaternion,
         );
-        const q = axisRotation(axis, action.angle).quaternion;
-        const axisPoint = shiftPoint(axisPose.position, axis.position);
+        const axisPoint = shiftPoint(axisPose.position, center);
         const rotatedAxis = rotatePoint(axisPoint, q);
         pose = {
           position: addPoints(
@@ -173,16 +200,19 @@ export function solveBodies(
   const preferences = new Map<string, Equation>();
   bodies.forEach((body, owner) =>
     body.relations.forEach(relation => {
-      // A chain describes contact followed by its explicit rotations. Invert only
-      // this chain; every other relation still sees and constrains the final pose.
-      const baseline = undoRotations(poses[owner], relation.rotations, poses);
-      // All authored contact stages contribute equally to the free-position
-      // choice. Deduplicate identical stages so repeated conditions add no bias.
+      // Every contact constrains the joint result before independent transforms.
+      const baseline = undoActions(
+        poses[owner],
+        body.transformations ?? [],
+        poses,
+      );
       for (let axis = 0; axis < 3; axis++) {
         const preference = {
           id: relation.id,
           coefficients: baseline.position.columns.map(column => column[axis]),
-          value: -baseline.position.constant[axis],
+          value:
+            (body.initial?.position[axis] ?? 0) -
+            baseline.position.constant[axis],
         };
         preferences.set(
           JSON.stringify([preference.coefficients, preference.value]),
@@ -212,14 +242,8 @@ export function solveBodies(
         source.position,
         rotateVector(center, targetFrame.quaternion),
       );
-      const targetPoint = shiftPoint(
-        target.position,
-        addVectors(
-          targetFrame.position,
-          rotateVector(relation.offset ?? origin, targetFrame.quaternion),
-        ),
-      );
-      for (const localAxis of relation.offset ? axes : [axes[1]]) {
+      const targetPoint = shiftPoint(target.position, targetFrame.position);
+      for (const localAxis of [axes[1]]) {
         const normal = rotateVector(localAxis, targetFrame.quaternion);
         equations.push({
           id: relation.id,
@@ -272,13 +296,18 @@ function addPoints(left: AffinePoint, right: AffinePoint): AffinePoint {
   };
 }
 
-function undoRotations(
+function undoActions(
   pose: AffinePose,
-  actions: readonly BodyRotation[],
+  actions: readonly BodyAction[],
   poses: readonly AffinePose[],
 ): AffinePose {
   for (const action of [...actions].reverse()) {
-    if ('local' in action) {
+    if ('offset' in action) {
+      pose = {
+        ...pose,
+        position: shiftPoint(pose.position, negateVector(action.offset)),
+      };
+    } else if ('local' in action) {
       const inverse = invertTransform(action.local);
       pose = {
         position: shiftPoint(
@@ -292,12 +321,13 @@ function undoRotations(
       };
     } else {
       const axisPose = poses[action.body];
-      const axis = composeTransforms(
-        rotation(axisPose.quaternion),
-        action.axis,
+      const {center, quaternion: q} = externalRotationFrame(
+        action,
+        pose.quaternion,
+        axisPose.quaternion,
+        true,
       );
-      const q = axisRotation(axis, -action.angle).quaternion;
-      const axisPoint = shiftPoint(axisPose.position, axis.position);
+      const axisPoint = shiftPoint(axisPose.position, center);
       const rotatedAxis = rotatePoint(axisPoint, q);
       pose = {
         position: addPoints(
@@ -316,7 +346,7 @@ function undoRotations(
 }
 
 /** Solve Ax=b, then minimize contact-stage displacement in its nullspace. */
-function solveTranslations(
+export function solveTranslations(
   equations: readonly Equation[],
   preferences: readonly Equation[],
   dimension: number,

package/src/library/cached.ts

@@ -0,0 +1,153 @@
+import {encodeKernelArtifact} from './kernel-artifact-codec.js';
+import {
+  acceptKernelOperation,
+  evaluateCachedArtifact,
+  findKernelOperation,
+  findKernelOperations,
+  kernelContentId,
+  kernelOperationKey,
+  type CacheCodec,
+  type KernelArtifact,
+  type KernelOperationKey,
+  type KernelValueLifecycle,
+} from './kernel-cache.js';
+import {estimateRetainedBytes} from './retained-memory.js';
+
+export type CacheOptions<Value> = CacheCodec<Value>;
+
+const identities = new WeakMap<Function, string>();
+const sessionIdentities = new WeakMap<Function, string>();
+const session = crypto.randomUUID();
+let nextIdentity = 0;
+
+/** The compiler supplies the definition and its static dependency fingerprint. */
+export function identifyCachedFunction<Fn extends Function>(
+  fn: Fn,
+  identity: string,
+): Fn {
+  // Identity belongs to this cache definition (including its codec), not to
+  // every other use of the author's original function object.
+  const identified = function (this: unknown, ...args: unknown[]) {
+    return Reflect.apply(fn, this, args);
+  } as unknown as Fn;
+  identities.set(identified, identity);
+  return identified;
+}
+
+function functionIdentity(fn: Function): {id: string; persistent: boolean} {
+  const identity = identities.get(fn);
+  if (identity) return {id: identity, persistent: true};
+  let id = sessionIdentities.get(fn);
+  if (!id) {
+    id = `${session}:${nextIdentity++}`;
+    sessionIdentities.set(fn, id);
+  }
+  // Without compiler fingerprints, object identity is the only sound identity
+  // for a JavaScript closure. It still shares the process-wide memory budget.
+  return {id, persistent: false};
+}
+
+const dataLifecycle: KernelValueLifecycle<unknown> = {
+  estimateBytes: estimateRetainedBytes,
+  retain: value => value,
+  instantiate: value => value,
+  release() {},
+};
+
+/**
+ * Memoizes a synchronous, deterministic computation in the shared cache.
+ * Omit args to create a function, or pass an argument tuple to return its value.
+ * Pass changing captured state as arguments and treat returned data as immutable.
+ * The engine fingerprints definitions and dependencies for persistent reuse.
+ * Outside the engine, function identity provides process-local memory reuse.
+ * Custom encoder/decoder pairs run only when writing/restoring persistent data;
+ * memory hits return the retained value without decoding or copying it.
+ */
+export function cache<Args extends unknown[], Value>(
+  compute: (
+    ...args: Args
+  ) => Value & (Value extends PromiseLike<unknown> ? never : unknown),
+  args: Readonly<NoInfer<Args>>,
+  options?: CacheOptions<NoInfer<Value>>,
+): Value;
+export function cache<Args extends unknown[], Value>(
+  compute: (
+    ...args: Args
+  ) => Value & (Value extends PromiseLike<unknown> ? never : unknown),
+  args?: undefined,
+  options?: CacheOptions<NoInfer<Value>>,
+): (...args: Args) => Value;
+export function cache<Args extends unknown[], Value>(
+  compute: (
+    ...args: Args
+  ) => Value & (Value extends PromiseLike<unknown> ? never : unknown),
+  args?: Readonly<Args>,
+  options?: CacheOptions<Value>,
+): Value | ((...args: Args) => Value) {
+  const operation = cachedArtifact(
+    (...args: Args): Value => {
+      const value = compute(...args);
+      if (
+        value &&
+        typeof value === 'object' &&
+        'then' in value &&
+        typeof value.then === 'function'
+      )
+        throw new Error('cache() requires a synchronous computation.');
+      return value;
+    },
+    {identity: compute, codec: options},
+  );
+  return args === undefined
+    ? (...args: Args) => operation(...args).value
+    : operation(...args).value;
+}
+
+/** Internal artifact form also supports native ownership and remote admission. */
+export function cachedArtifact<Args extends unknown[], Value>(
+  compute: (...args: Args) => Value,
+  {
+    key,
+    lifecycle = dataLifecycle as KernelValueLifecycle<Value>,
+    codec,
+    identity = compute,
+    namespace = 'cached',
+  }: {
+    key?: (...args: Args) => KernelOperationKey;
+    lifecycle?: KernelValueLifecycle<Value>;
+    codec?: CacheCodec<Value> | false;
+    identity?: Function;
+    namespace?: string;
+  } = {},
+) {
+  const definition = functionIdentity(identity);
+  const persistence = key || definition.persistent ? codec : false;
+  const operationKey =
+    key ??
+    ((...args: Args) =>
+      kernelOperationKey(
+        namespace,
+        [definition.id, kernelContentId(encodeKernelArtifact('', args))],
+        [],
+      ));
+  const find = (key: KernelOperationKey) =>
+    findKernelOperation(key, lifecycle, persistence);
+  const findMany = (keys: readonly KernelOperationKey[]) =>
+    findKernelOperations(keys, lifecycle, persistence);
+  const accept = (
+    key: KernelOperationKey,
+    value: Value,
+    milliseconds: number,
+  ) => acceptKernelOperation(key, lifecycle, value, milliseconds, persistence);
+  return Object.assign(
+    (...args: Args): KernelArtifact<Value> => {
+      return evaluateCachedArtifact(
+        operationKey(...args),
+        lifecycle,
+        () => compute(...args),
+        persistence,
+      );
+    },
+    {key: operationKey, find, findMany, accept},
+  );
+}