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

package/src/library/cached.ts

@@ -0,0 +1,132 @@
+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 CachedOptions<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.
+ * 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 cached<Args extends unknown[], Value>(
+  compute: (
+    ...args: Args
+  ) => Value & (Value extends PromiseLike<unknown> ? never : unknown),
+  options?: CachedOptions<NoInfer<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('cached() requires a synchronous computation.');
+      return value;
+    },
+    {identity: compute, codec: options},
+  );
+  return (...args) => 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) =>
+    acceptKernelOperation(key, lifecycle, value, persistence);
+  return Object.assign(
+    (...args: Args): KernelArtifact<Value> => {
+      return evaluateCachedArtifact(
+        operationKey(...args),
+        lifecycle,
+        () => compute(...args),
+        persistence,
+      );
+    },
+    {key: operationKey, find, findMany, accept},
+  );
+}

package/src/library/font.ts

@@ -0,0 +1,186 @@
+/// <reference types="emscripten" preserve="true" />
+import {cachedArtifact} from './cached.js';
+import type * as HarfBuzz from 'harfbuzzjs';
+import {
+  googleFontSources,
+  googleFontUrl,
+  type GoogleFontOptions,
+} from './google-font.js';
+import {
+  kernelOperationKey,
+  kernelContentId,
+  type KernelArtifact,
+} from './kernel-cache.js';
+
+const fontBrand: unique symbol = Symbol('Font');
+/** An immutable, content-addressed font resource. Size is supplied to text(). */
+export type Font = Readonly<{
+  family: string;
+  style: string;
+  [fontBrand]: true;
+}>;
+export type ParsedFont = Readonly<{
+  face: HarfBuzz.Face;
+  font: HarfBuzz.Font;
+  numGlyphs: number;
+  sourceBytes: number;
+}>;
+let fontEngine: typeof HarfBuzz;
+let shapingBuffer: HarfBuzz.Buffer;
+export function installFontEngine(engine: typeof HarfBuzz): void {
+  fontEngine = engine;
+  shapingBuffer = new engine.Buffer();
+}
+export function shapeFontText(
+  font: HarfBuzz.Font,
+  content: string,
+  kerning: boolean,
+) {
+  shapingBuffer.reset();
+  shapingBuffer.addText(content);
+  shapingBuffer.guessSegmentProperties();
+  fontEngine.shape(font, shapingBuffer, [
+    new fontEngine.Feature('kern', Number(kerning)),
+  ]);
+  return {
+    infos: shapingBuffer.getGlyphInfos(),
+    positions: shapingBuffer.getGlyphPositions(),
+  };
+}
+export type FontPart = Readonly<{
+  artifact: KernelArtifact<ParsedFont>;
+  ranges: readonly (readonly [number, number])[];
+}>;
+const fonts = new WeakMap<Font, readonly FontPart[]>();
+let readResource: ((url: URL) => Uint8Array | undefined) | undefined;
+
+/** The model engine prepares resources before synchronous author code runs. */
+export function installModelResourceReader(reader: typeof readResource): void {
+  readResource = reader;
+}
+
+/** Reads font bytes or a prepared project/HTTP(S) URL; Node also reads file URLs. */
+export function font(source: URL | ArrayBuffer | Uint8Array): Font {
+  return fontValue([{artifact: parseFont(source), ranges: []}]);
+}
+
+/**
+ * A Google Fonts family/style prepared by the model engine before execution.
+ * @modelResource google-font
+ */
+export function googleFont(
+  family: string,
+  options: GoogleFontOptions = {},
+): Font {
+  const url = googleFontUrl(family, options);
+  const css = readResource?.(url);
+  if (!css)
+    throw new Error(
+      'googleFont() requires resources prepared by the model engine. Use a static family name and options.',
+    );
+  return fontValue(
+    googleFontSources(css).map(({url, ranges}) => ({
+      artifact: parseFont(new URL(url), options),
+      ranges,
+    })),
+  );
+}
+
+function parseFont(
+  source: URL | ArrayBuffer | Uint8Array,
+  options: GoogleFontOptions = {},
+): KernelArtifact<ParsedFont> {
+  if (!fontEngine) throw new Error('The font engine has not been initialized.');
+  const bytes =
+    source instanceof URL
+      ? readResource?.(source)
+      : source instanceof ArrayBuffer
+        ? new Uint8Array(source)
+        : source;
+  if (!(bytes instanceof Uint8Array)) {
+    throw new Error(
+      'font() requires font bytes or a URL prepared by the model engine. Use a static new URL("./font.ttf", import.meta.url) or new URL("https://…/font.ttf"); outside the engine, fetch the font first and pass its bytes.',
+    );
+  }
+  return parsedFont(bytes, options);
+}
+
+const parsedFont = cachedArtifact(
+  (bytes: Uint8Array, options: GoogleFontOptions): ParsedFont => {
+    try {
+      const signature = new DataView(
+        bytes.buffer,
+        bytes.byteOffset,
+        bytes.byteLength,
+      ).getUint32(0);
+      if (signature !== 0x00010000 && signature !== 0x4f54544f)
+        throw new Error('Expected an SFNT font.');
+      const face = new fontEngine.Face(new fontEngine.Blob(bytes));
+      const maxp = face.referenceTable('maxp');
+      if (!maxp || maxp.byteLength < 6 || !face.referenceTable('cmap'))
+        throw new Error('Missing font tables.');
+      const numGlyphs = new DataView(
+        maxp.buffer,
+        maxp.byteOffset,
+        maxp.byteLength,
+      ).getUint16(4);
+      if (!numGlyphs) throw new Error('Font has no glyphs.');
+      const font = new fontEngine.Font(face);
+      const variations: HarfBuzz.Variation[] = [];
+      if (options.weight !== undefined)
+        variations.push(new fontEngine.Variation('wght', options.weight));
+      if (options.italic !== undefined)
+        variations.push(
+          new fontEngine.Variation('ital', Number(options.italic)),
+        );
+      font.setVariations(variations);
+      return {face, font, numGlyphs, sourceBytes: bytes.byteLength};
+    } catch (error) {
+      throw new Error(
+        'Cannot parse font. Expected a TTF or OTF font (font collections and WOFF2 are not supported).',
+        {cause: error},
+      );
+    }
+  },
+  {
+    key: (bytes, options) =>
+      kernelOperationKey(
+        'font',
+        [
+          kernelContentId(bytes),
+          bytes.byteLength,
+          options.weight ?? null,
+          options.italic ?? null,
+        ],
+        [],
+      ),
+    codec: false,
+    lifecycle: {
+      // Account for parser tables and lazy glyph expansion in the shared budget.
+      estimateBytes: value => value.sourceBytes * 8 + value.numGlyphs * 1024,
+      retain: value => value,
+      instantiate: value => value,
+      release() {},
+    },
+  },
+);
+
+function fontValue(parts: readonly FontPart[]): Font {
+  const parsed = parts[0].artifact.value;
+  const value: Font = Object.freeze({
+    family: parsed.face.getName(1, 'en'),
+    style: parsed.face.getName(2, 'en'),
+    [fontBrand]: true as const,
+  });
+  fonts.set(value, parts);
+  return value;
+}
+
+export function fontParts(value: Font): readonly FontPart[] {
+  const parts = fonts.get(value);
+  if (!parts)
+    throw new Error(
+      'text() requires a font created by font() or googleFont().',
+    );
+  return parts;
+}

package/src/library/google-font.ts

@@ -0,0 +1,97 @@
+import {cachedArtifact} from './cached.js';
+import {kernelContentId, kernelOperationKey} from './kernel-cache.js';
+
+export type GoogleFontOptions = Readonly<{
+  /** Omit to use Google Fonts' default weight. */
+  weight?: number;
+  /** Omit to use Google Fonts' default style. */
+  italic?: boolean;
+}>;
+
+export type GoogleFontSource = Readonly<{
+  url: string;
+  ranges: readonly (readonly [number, number])[];
+}>;
+
+/** Canonical request shared by synchronous Core and asynchronous preparation. */
+export function googleFontUrl(
+  family: string,
+  options: GoogleFontOptions = {},
+): URL {
+  if (typeof family !== 'string' || !family.trim())
+    throw new Error('Google font family must be a non-empty name.');
+  if (
+    options.weight !== undefined &&
+    (!Number.isFinite(options.weight) ||
+      options.weight < 1 ||
+      options.weight > 1000)
+  )
+    throw new Error('Google font weight must be between 1 and 1000.');
+  if (options.italic !== undefined && typeof options.italic !== 'boolean')
+    throw new Error('Google font italic must be a boolean.');
+  const axes: [string, number][] = [];
+  if (options.italic !== undefined) axes.push(['ital', Number(options.italic)]);
+  if (options.weight !== undefined) axes.push(['wght', options.weight]);
+  const specification =
+    family.trim() +
+    (axes.length
+      ? ':' +
+        axes.map(([axis]) => axis).join(',') +
+        '@' +
+        axes.map(([, value]) => value).join(',')
+      : '');
+  return new URL(
+    'https://fonts.googleapis.com/css2?' +
+      new URLSearchParams({family: specification}),
+  );
+}
+
+/** Parse only font-face resource declarations; no stylesheet is installed. */
+const parseGoogleFontSources = cachedArtifact(
+  (bytes: Uint8Array): readonly GoogleFontSource[] => {
+    const css = new TextDecoder()
+      .decode(bytes)
+      .replace(/\/\*[\s\S]*?\*\//g, '');
+    const sources: GoogleFontSource[] = [];
+    for (const [, body] of css.matchAll(/@font-face\s*\{([^}]*)\}/gi)) {
+      const source = /(?:^|;)\s*src\s*:\s*([^;]+)/i.exec(body)?.[1];
+      const rawUrl =
+        source &&
+        /url\(\s*(?:"([^"]+)"|'([^']+)'|([^\s)]+))\s*\)/i.exec(source);
+      if (!rawUrl)
+        throw new Error('Google Fonts returned a font face without a URL.');
+      const url = new URL(rawUrl[1] ?? rawUrl[2] ?? rawUrl[3]);
+      if (url.protocol !== 'https:')
+        throw new Error('Google Fonts returned a non-HTTPS font URL.');
+      const ranges: [number, number][] = [];
+      const range = /(?:^|;)\s*unicode-range\s*:\s*([^;]+)/i.exec(body)?.[1];
+      if (range)
+        for (const part of range.split(',')) {
+          const match =
+            /^\s*U\+([0-9a-f?]{1,6})(?:-([0-9a-f]{1,6}))?\s*$/i.exec(part);
+          if (!match)
+            throw new Error('Google Fonts returned an invalid Unicode range.');
+          const start = parseInt(match[1].replaceAll('?', '0'), 16);
+          const end = parseInt(match[2] ?? match[1].replaceAll('?', 'f'), 16);
+          if (start > end || end > 0x10ffff)
+            throw new Error('Google Fonts returned an invalid Unicode range.');
+          ranges.push([start, end]);
+        }
+      sources.push({url: url.href, ranges});
+    }
+    if (!sources.length)
+      throw new Error('Google Fonts returned no font files.');
+    // Later CSS faces take precedence where Unicode ranges overlap.
+    return sources.reverse();
+  },
+  {
+    key: bytes =>
+      kernelOperationKey('googleFontSources', [kernelContentId(bytes)], []),
+  },
+);
+
+export function googleFontSources(
+  bytes: Uint8Array,
+): readonly GoogleFontSource[] {
+  return parseGoogleFontSources(bytes).value;
+}

package/src/library/index.ts

@@ -1,3 +1,9 @@
+export {cached} from './cached.js';
+export type {CachedOptions} from './cached.js';
+export {font, googleFont} from './font.js';
+export type {Font} from './font.js';
+export type {GoogleFontOptions} from './google-font.js';
+export type {TextOptions} from './text.js';
 export {sketch} from './sketch.js';
 export type {
   Sketch,
@@ -19,6 +25,7 @@ export {
   cylinder,
   ellipse,
   extrude,
+  text,
   frustum,
   group,
   intersect,
@@ -61,9 +68,7 @@ export type {
   Model,
   ModelCapabilities,
   ModelElementKind,
-  ModelFamily,
-  ModelFamilyElementKind,
-  ModelForFamily,
+  ModelForKind,
   ModelGeometryKind,
   ModelKind,
   NamedElements,

package/src/library/kernel-artifact-codec.ts

@@ -8,12 +8,31 @@ const decoder = new TextDecoder('utf-8', {fatal: true});
 // references. Native handles never escape their runtime; only BinTools bytes do.
 type Node = null | boolean | string | number | readonly [string, unknown];
 
+const binaryTypes: Record<
+  string,
+  new (buffer: ArrayBuffer, offset?: number, length?: number) => ArrayBufferView
+> = {
+  Int8Array,
+  Uint8Array,
+  Uint8ClampedArray,
+  Int16Array,
+  Uint16Array,
+  Int32Array,
+  Uint32Array,
+  Float32Array,
+  Float64Array,
+  BigInt64Array,
+  BigUint64Array,
+  DataView,
+};
+
 export function encodeKernelArtifact(
   signature: string,
   value: unknown,
 ): Uint8Array {
   const chunks: Uint8Array[] = [];
   let offset = 0;
+  const references = new Map<object, number>();
   function binary(kind: string, bytes: Uint8Array): Node {
     const node: Node = [kind, [offset, bytes.byteLength]];
     chunks.push(bytes);
@@ -32,21 +51,56 @@ export function encodeKernelArtifact(
       typeof value === 'boolean'
     )
       return value;
+    if (typeof value === 'bigint') return ['bigint', String(value)];
+    if (typeof value !== 'object')
+      throw new Error('Unsupported kernel artifact value');
+    const existing = references.get(value);
+    if (existing !== undefined) return ['reference', existing];
+    const id = references.size;
+    references.set(value, id);
+    return ['value', [id, encodeObject(value)]];
+  }
+  function encodeObject(value: object): Node {
     if (value instanceof Shape)
       return binary('shape', encodeShape(value as AnyShape));
-    if (value instanceof Float32Array || value instanceof Uint32Array) {
-      return binary(
-        value instanceof Float32Array ? 'float32' : 'uint32',
-        new Uint8Array(value.buffer, value.byteOffset, value.byteLength),
-      );
+    if (ArrayBuffer.isView(value)) {
+      if (!Object.hasOwn(binaryTypes, value.constructor.name))
+        throw new Error('Unsupported kernel artifact view');
+      return [
+        'view',
+        [
+          value.constructor.name,
+          encode(value.buffer),
+          value.byteOffset,
+          value instanceof DataView
+            ? value.byteLength
+            : (value as unknown as {length: number}).length,
+        ],
+      ];
     }
-    if (Array.isArray(value)) return ['array', value.map(encode)];
+    if (value instanceof ArrayBuffer)
+      return binary('ArrayBuffer', new Uint8Array(value));
+    if (value instanceof Date) return ['date', encode(value.getTime())];
+    if (value instanceof Map)
+      return [
+        'map',
+        [...value].map(([key, item]) => [encode(key), encode(item)]),
+      ];
+    if (value instanceof Set) return ['set', [...value].map(encode)];
+    if (Array.isArray(value))
+      return [
+        'array',
+        [
+          value.length,
+          Object.entries(value).map(([key, item]) => [key, encode(item)]),
+        ],
+      ];
     if (
-      typeof value === 'object' &&
-      Object.getPrototypeOf(value) === Object.prototype
+      Object.getPrototypeOf(value) === Object.prototype ||
+      Object.getPrototypeOf(value) === null
     ) {
       return [
-        'object',
+        Object.getPrototypeOf(value) === null ? 'record' : 'object',
         Object.entries(value).map(([key, item]) => [key, encode(item)]),
       ];
     }
@@ -81,23 +135,79 @@ export function decodeKernelArtifact<Value>(
   if (storedSignature !== signature)
     throw new Error('Kernel artifact signature mismatch');
   const shapes: AnyShape[] = [];
-  function decode(node: Node): unknown {
+  const references = new Map<number, unknown>();
+  function decode(node: Node, referenceId?: number): unknown {
+    const register = <T>(value: T): T => {
+      if (referenceId !== undefined) references.set(referenceId, value);
+      return value;
+    };
     if (!Array.isArray(node)) return node;
     const [kind, data] = node;
     switch (kind) {
+      case 'reference':
+        if (!references.has(data as number))
+          throw new Error('Invalid kernel artifact reference');
+        return references.get(data as number);
+      case 'value': {
+        const [id, value] = data as [number, Node];
+        return decode(value, id);
+      }
       case 'undefined':
         return undefined;
       case 'number':
         return Number(data);
+      case 'bigint':
+        return BigInt(data as string);
+      case 'date':
+        return register(new Date(decode(data as Node) as number));
+      case 'map': {
+        const map = register(new Map());
+        for (const [key, item] of data as [Node, Node][])
+          map.set(decode(key), decode(item));
+        return map;
+      }
+      case 'set': {
+        const set = register(new Set());
+        for (const item of data as Node[]) set.add(decode(item));
+        return set;
+      }
       case 'array':
-        return (data as Node[]).map(decode);
-      case 'object':
-        return Object.fromEntries(
-          (data as [string, Node][]).map(([key, item]) => [key, decode(item)]),
+      case 'record':
+      case 'object': {
+        const object = register(
+          kind === 'array'
+            ? new Array((data as [number, unknown])[0])
+            : kind === 'record'
+              ? Object.create(null)
+              : {},
         );
+        const entries = (
+          kind === 'array' ? (data as [number, unknown])[1] : data
+        ) as [string, Node][];
+        for (const [key, item] of entries)
+          Object.defineProperty(object, key, {
+            value: decode(item),
+            writable: true,
+            configurable: true,
+            enumerable: true,
+          });
+        return object;
+      }
+      case 'view': {
+        const [name, buffer, offset, length] = data as [
+          string,
+          Node,
+          number,
+          number,
+        ];
+        if (!Object.hasOwn(binaryTypes, name))
+          throw new Error('Invalid kernel artifact view');
+        return register(
+          new binaryTypes[name](decode(buffer) as ArrayBuffer, offset, length),
+        );
+      }
       case 'shape':
-      case 'float32':
-      case 'uint32': {
+      case 'ArrayBuffer': {
         const [offset, length] = data as number[];
         if (
           !Number.isSafeInteger(offset) ||
@@ -108,13 +218,12 @@ export function decodeKernelArtifact<Value>(
         ) {
           throw new Error('Invalid kernel artifact binary range');
         }
-        // Each retained array owns exactly its bytes, not the whole disk record.
+        // Each restored backing buffer owns its source bytes, not the disk record.
         const chunk = bytes.slice(start + offset, start + offset + length);
-        if (kind === 'float32') return new Float32Array(chunk.buffer);
-        if (kind === 'uint32') return new Uint32Array(chunk.buffer);
+        if (kind === 'ArrayBuffer') return register(chunk.buffer);
         const shape = decodeShape(chunk);
         shapes.push(shape);
-        return shape;
+        return register(shape);
       }
       default:
         throw new Error('Invalid kernel artifact node');