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

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,37 @@
+export {cache} from './cached.js';
+export type {CacheOptions} from './cached.js';
+export {
+  dimension,
+  boundsAnnotation,
+  anchorAnnotation,
+  captureInspectData,
+} from './inspect.js';
+/** @internal */
+export {
+  relate,
+  on,
+  align,
+  expose,
+  inspectTopologyReference,
+} from './runtime.js';
+export type {
+  Dimension,
+  DimensionSegment,
+  BoundsAnnotation,
+  AnchorAnnotation,
+  PreviewValue,
+  InspectResult,
+  InspectCall,
+  InspectClosureExecution,
+  InspectContextFactory,
+  InspectClosure,
+  InspectContext,
+  Inspector,
+} from './inspect.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,
@@ -10,6 +44,13 @@ export type {
 } from './sketch.js';
 
 export {
+  offset,
+  rotate,
+  pivot,
+  pivotVertex,
+  pivotPoint,
+  axisEdge,
+  axisLine,
   arc,
   bezier,
   box,
@@ -17,8 +58,10 @@ export {
   coil,
   cut,
   cylinder,
+  distance,
   ellipse,
   extrude,
+  text,
   frustum,
   group,
   intersect,
@@ -38,8 +81,13 @@ export type {
   Anchor,
   Bound,
   DirectionalBounds,
-  ConstraintPivotChain,
-  ConstraintAroundChain,
+  DistanceAxis,
+  PivotChain,
+  PivotRotation,
+  AxisRotation,
+  AxisChain,
+  Transformation,
+  Relation,
   CanonicalElements,
   Constraint,
   CurveElements,
@@ -51,6 +99,7 @@ export type {
   ExposedElements,
   ExposedValue,
   FaceAnchor,
+  FrameAnchor,
   FaceModel,
   GeometryCapabilities,
   GeometryQueryCapabilities,
@@ -60,10 +109,9 @@ export type {
   MergedElements,
   Model,
   ModelCapabilities,
+  ModelBounds,
   ModelElementKind,
-  ModelFamily,
-  ModelFamilyElementKind,
-  ModelForFamily,
+  ModelForKind,
   ModelGeometryKind,
   ModelKind,
   NamedElements,

package/src/library/inspect.ts

@@ -0,0 +1,178 @@
+import type {Anchor, Model, SolidModel} from './runtime.js';
+import type {Sketch, SketchPoint} from './sketch.js';
+import type {RigidTransform, Vec3} from './spatial.js';
+
+let recordData: ((data: unknown) => void) | undefined;
+const inspectionIdentities = new WeakMap<object, object>();
+
+/** Runtime-only identity of a value retained in a different inspection frame. */
+export function inspectionIdentity(value: object): object {
+  return inspectionIdentities.get(value) ?? value;
+}
+
+/** Frame changes preserve the inspected object, unlike newly generated geometry. */
+export function retainInspectionIdentity<T extends object>(
+  value: T,
+  source: object,
+): T {
+  inspectionIdentities.set(value, inspectionIdentity(source));
+  return value;
+}
+
+/** Avoid preparing call data when no execution host is recording it. */
+export function isRecordingInspection(): boolean {
+  return recordData !== undefined;
+}
+
+/**
+ * Attach data to the current inspected call without changing its return value.
+ * The inspector receives the last recorded value as context.data. Data stays in
+ * the execution host by reference; capture immutable values for call-time facts.
+ * Without a recording scope this function does nothing.
+ */
+export function captureInspectData(data: unknown): void {
+  recordData?.(data);
+}
+
+/** The execution host supplies the current call's recording scope (tooling entry only). */
+export function recordInspectionCalls(
+  record: (data: unknown) => void,
+): () => void {
+  const previous = recordData;
+  recordData = record;
+  return () => {
+    recordData = previous;
+  };
+}
+
+/** A finite segment expressed in an annotation owner's local coordinates. */
+export type DimensionSegment = Readonly<{start: Vec3; end: Vec3}>;
+
+type DimensionLines =
+  DimensionSegment | Readonly<{candidates: readonly DimensionSegment[]}>;
+type DimensionOptions = Readonly<{
+  owner: Model;
+  value: number;
+  axisLabel?: string;
+}>;
+
+/** A passive dimension; a candidate is selected on entry and retained while inspecting it. */
+export type Dimension = Readonly<{kind: 'dimension'}> &
+  DimensionOptions &
+  DimensionLines;
+
+/** Create a preview annotation without adding CAD geometry. */
+export function dimension(value: DimensionOptions & DimensionLines): Dimension {
+  if ('candidates' in value && !value.candidates.length)
+    throw new Error(
+      'A dimension annotation requires at least one candidate segment.',
+    );
+  return {kind: 'dimension', ...value};
+}
+
+/** Exact finite extent, centered in a frame local to its owner; not CAD geometry. */
+export type BoundsAnnotation = Readonly<{
+  kind: 'bounds';
+  owner: Model;
+  size: Vec3;
+  frame: RigidTransform;
+}>;
+
+/** Draw the existing screen-sized bounds corners without creating a solid. */
+export function boundsAnnotation(
+  value: Omit<BoundsAnnotation, 'kind'>,
+): BoundsAnnotation {
+  return {kind: 'bounds', ...value};
+}
+
+/** Render the same reference with explicit direction markers. */
+export type AnchorAnnotation = Readonly<{
+  kind: 'anchor-annotation';
+  anchor: Anchor;
+  direction: 'none' | 'forward' | 'both';
+}>;
+
+export function anchorAnnotation(
+  anchor: Anchor,
+  options: Pick<AnchorAnnotation, 'direction'>,
+): AnchorAnnotation {
+  return retainInspectionIdentity(
+    {kind: 'anchor-annotation', anchor, ...options},
+    anchor,
+  );
+}
+
+/** Values accepted by the App's ordinary object preview. */
+export type PreviewValue =
+  | Model
+  | Anchor
+  | Sketch
+  | SketchPoint
+  | Dimension
+  | BoundsAnnotation
+  | AnchorAnnotation;
+
+/** One inspector owns the complete scene; undefined declines its scope. */
+export type InspectResult = Readonly<{
+  ambient?: readonly PreviewValue[];
+  target?: readonly PreviewValue[];
+}>;
+
+export type InspectCall = Readonly<{
+  receiver: unknown;
+  arguments: readonly unknown[];
+  return: unknown;
+  data: unknown;
+}>;
+
+/** The actual invocation of a callback declared with @code3d.inspect.closure/context. */
+export type InspectClosureExecution = Readonly<{
+  arguments: readonly unknown[];
+  return: unknown;
+  call: InspectCall;
+  parent?: InspectClosure;
+}>;
+
+export type InspectContextFactory<Data = unknown> = (
+  execution: InspectClosureExecution,
+) => Data;
+
+export type InspectClosure = InspectClosureExecution &
+  Readonly<{
+    provider?: InspectContextFactory;
+    data: unknown;
+  }>;
+
+/** Inspection belongs to an invoked call, independently of tool selection.
+ * A thrown call has no return value; recorded data and evaluated arguments remain available.
+ * Calls not reached because an argument throws have no inspection invocation.
+ */
+export type InspectContext<
+  Return = unknown,
+  Receiver = unknown,
+  Data = unknown,
+> = Readonly<{
+  receiver: Receiver;
+  return: Return | undefined;
+  data: Data;
+  closure?: InspectClosure;
+  focused: Readonly<{
+    value: unknown;
+    parameter: string | undefined;
+    path: readonly (string | number)[];
+    values: readonly PreviewValue[];
+    solids: readonly SolidModel<{}>[];
+    /** Absolute placement prefix count when the caret is at a relate array gap. */
+    insertion?: number;
+  }>;
+}>;
+
+export type Inspector<
+  Args extends readonly unknown[] = readonly unknown[],
+  Return = unknown,
+  Receiver = unknown,
+  Data = unknown,
+> = (
+  args: Args,
+  context: InspectContext<Return, Receiver, Data>,
+) => InspectResult | undefined;