@squinch/core 0.1.0

package/dist/render/validate.d.ts

@@ -0,0 +1,4 @@
+export declare function validateSVG(svg: string): {
+    ok: boolean;
+    error?: string;
+};

package/dist/render/validate.js

@@ -0,0 +1,9 @@
+// Real XML validation for every rendered SVG — duplicate attributes, unclosed
+// tags, bad entities. Cheap enough to run on every render in tests and tools.
+import { XMLValidator } from "fast-xml-parser";
+export function validateSVG(svg) {
+    const result = XMLValidator.validate(svg, { allowBooleanAttributes: false });
+    if (result === true)
+        return { ok: true };
+    return { ok: false, error: `${result.err.msg} (line ${result.err.line}, col ${result.err.col})` };
+}

package/dist/themes/index.d.ts

@@ -0,0 +1,84 @@
+import type { Hue } from "../model/types.js";
+export interface ThemeFont {
+    /** CSS font-family stack; first entry is the embedded face's family name. */
+    css: string;
+    /** which metrics/embedding family backs this theme */
+    metrics: "inter";
+    /** Multiplies emitted font sizes AND text measurement, so layout stays
+     *  truthful. 1 for every shipping theme; the hook survives the sketch theme
+     *  it was built for because a future display face may run small again. */
+    scale: number;
+}
+export interface Theme {
+    name: string;
+    canvas: string;
+    surface: string;
+    border: string;
+    ink: string;
+    muted: string;
+    edge: string;
+    asyncEdge: string;
+    plateText: string;
+    accent: string;
+    /** Ink inside a flow bead — dark on the light-on-dark bead, white on the
+     *  saturated light one, so the number reads at 10px either way. */
+    beadText: string;
+    /** Warning-note plate. On its way out: docs/design retires the amber fill
+     *  (the only third hue in a two-hue palette, and it read as a sticky note),
+     *  and the distinction moves to a glyph. It stays until that glyph exists —
+     *  dropping it first would silently erase an authored `style: warning`. */
+    warnTint: string;
+    surfaceAlt: string;
+    /** The card gradient's two stops, top to bottom: a 4% ramp that reads as a
+     *  lit surface rather than a flat fill (docs/design). `surfaceLo` is also
+     *  the shelf, so the strip along a card's bottom continues the same surface
+     *  instead of reading as a separate block. */
+    surfaceHi: string;
+    surfaceLo: string;
+    /** Hairline between a card's body and its shelf — lighter than `border`,
+     *  because it divides one surface rather than bounding two. */
+    shelfLine: string;
+    /** The neutral chip an icon sits on: card plates, glyph chips, shelf chips.
+     *  Doubles as the actor tile's upper tone — an actor is a filled shape, and
+     *  this is the quietest fill that still separates from canvas. */
+    plate: string;
+    /** The actor tile's lower gradient stop, a step under `plate`. */
+    actorLo: string;
+    /** The stacked sheets behind a container — "there is more inside". Quieter
+     *  than the card's own border and fill: a hint, not a stack of real cards. */
+    sheetFill: string;
+    sheetBorder: string;
+    /** Dimmer than `muted`: a note's glyph, the title block's date — present,
+     *  but never the thing read first. */
+    faint: string;
+    /** Dimmest tone that still passes as text: the footer wordmark. */
+    dim: string;
+    /** The 1px contact shadow under cards, leaves, actors and notes. rgba, not
+     *  hex: the alpha is the whole effect, and it must ride `flood-color` for
+     *  the adaptive merge to treat it as colour rather than geometry. */
+    shadow: string;
+    font: ThemeFont;
+    /** The dark counterpart this theme can share one adaptive file with. Only
+     *  themes with the same font can pair: type metrics drive layout, so a
+     *  cross-font pair would draw two different diagrams. */
+    pairsWith?: string;
+    /** The eight author hues (SPEC `color:`), one designed pair per theme —
+     *  darker and more saturated on paper, lifted on the dark canvas. Also the
+     *  zone kind tints (DESIGN §5: account→red, network→blue, cloud→violet,
+     *  the rest→gray). 6-digit hex only: the zone chip concatenates an alpha
+     *  byte onto these. */
+    hueRed: string;
+    hueAmber: string;
+    hueGreen: string;
+    hueTeal: string;
+    hueBlue: string;
+    hueViolet: string;
+    huePink: string;
+    hueGray: string;
+}
+/** The one place a hue name becomes a colour. `accent` is the brand token
+ *  rather than a ninth pair, so it stays whatever the theme says it is. */
+export declare const hueOf: (t: Theme, h: Hue) => string;
+export declare const light: Theme;
+export declare const dark: Theme;
+export declare const themes: Record<string, Theme>;

package/dist/themes/index.js

@@ -0,0 +1,90 @@
+/** The one place a hue name becomes a colour. `accent` is the brand token
+ *  rather than a ninth pair, so it stays whatever the theme says it is. */
+export const hueOf = (t, h) => h === "accent" ? t.accent : t[`hue${h[0].toUpperCase()}${h.slice(1)}`];
+const inter = {
+    css: "SquinchInter, Inter, system-ui, sans-serif",
+    metrics: "inter",
+    scale: 1,
+};
+export const light = {
+    name: "light",
+    font: inter,
+    pairsWith: "dark",
+    // red/blue/violet/gray are the former zone tints, verbatim, so every zone
+    // ever rendered is byte-identical; the other four were designed beside them
+    hueRed: "#B5544C",
+    hueAmber: "#A06B12",
+    hueGreen: "#3F8A5C",
+    hueTeal: "#1F8A80",
+    hueBlue: "#3A6EA8",
+    hueViolet: "#6B5FC9",
+    huePink: "#B04A8A",
+    hueGray: "#7A776E",
+    canvas: "#F7F7F5",
+    surface: "#FFFFFF",
+    border: "#EAE9E5",
+    ink: "#1C1C1A",
+    muted: "#6F6E69",
+    edge: "#57564F",
+    // one purple, not two: the design exploration shipped #7C74D9 for async
+    // beside #5A57C9 for flow beads and flagged them as indistinguishable
+    asyncEdge: "#5A57C9",
+    plateText: "#FFFFFF",
+    accent: "#5A57C9",
+    beadText: "#FFFFFF",
+    warnTint: "#FBF3DC",
+    surfaceAlt: "#EFEFEC",
+    surfaceHi: "#FFFFFF",
+    surfaceLo: "#F2F1ED",
+    shelfLine: "#EFEFEC",
+    plate: "#EFEFEC",
+    actorLo: "#E4E3DE",
+    faint: "#8A8880",
+    dim: "#A5A199",
+    sheetFill: "#F2F1ED",
+    sheetBorder: "#DEDDD6",
+    shadow: "rgba(28,28,26,0.06)",
+};
+export const dark = {
+    name: "dark",
+    font: inter,
+    hueRed: "#D08078",
+    hueAmber: "#D9B168",
+    hueGreen: "#6FC29A",
+    hueTeal: "#4AC4B8",
+    hueBlue: "#6E9CD0",
+    hueViolet: "#9C93E8",
+    huePink: "#D685BB",
+    hueGray: "#8F8C82",
+    canvas: "#161618",
+    surface: "#212124",
+    border: "#3B3B40",
+    ink: "#EDEDEA",
+    muted: "#9C9B94",
+    edge: "#8D8C84",
+    asyncEdge: "#8B88E8",
+    plateText: "#FFFFFF",
+    accent: "#8B88E8",
+    // the dark bead is a light lavender disc, so its number is ink, not white
+    beadText: "#1B1B2E",
+    warnTint: "#3A3423",
+    surfaceAlt: "#1D1D20",
+    surfaceHi: "#26262A",
+    surfaceLo: "#1D1D20",
+    shelfLine: "#2E2E33",
+    plate: "#2F2F34",
+    actorLo: "#26262A",
+    faint: "#7A796F",
+    dim: "#6E6D67",
+    sheetFill: "#1D1D20",
+    sheetBorder: "#33333A",
+    shadow: "rgba(0,0,0,0.5)",
+};
+// Light and dark are the shipping pair. The sketch, sketch-dark and contrast
+// themes were retired in the docs/design restyle (2026-08): the restyle's card
+// anatomy — gradient ramps, contact shadows, the stacked-sheet affordance, the
+// segmented chip grammar — is a designed surface with no hand-drawn or
+// pure-black translation, and three unreviewed palettes silently riding every
+// geometry change is a cost with no reader. Adding a theme back means designing
+// it against docs/design, not swapping a palette.
+export const themes = { light, dark };

package/dist/view/dive.d.ts

@@ -0,0 +1,55 @@
+export interface Box {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+/** How far the eye travels. Anything past ~3× reads as a jump cut, not a move. */
+export declare const CAP = 3.2;
+/** The incoming layer travels a fraction of the outgoing one — a full mirror
+ *  overshoots and feels like two separate animations played back to back. */
+export declare const TRAVEL = 0.62;
+/** The dive itself, and the anchorless fallback for a hop between two views at
+ *  the same altitude, where there is no shared card to travel through. */
+export declare const DIVE: {
+    ms: number;
+    ease: string;
+};
+export declare const CUT: {
+    ms: number;
+    ease: string;
+};
+export declare const centre: (b: Box) => {
+    x: number;
+    y: number;
+};
+export declare const clamp: (v: number, lo: number, hi: number) => number;
+/** Scale factor for a dive through `anchor` within `view`, clamped both ways. */
+export declare const scaleFor: (view: Box, anchor: Box) => number;
+export interface DiveInput {
+    /** the visible canvas, in canvas space */
+    view: Box;
+    /** the outgoing layer's box */
+    ghostBox: Box;
+    /** the incoming layer's box */
+    liveBox: Box;
+    /** the shared card. Absent = a lateral hop, which gets the cut instead. */
+    anchor?: Box;
+    dir: "in" | "out";
+}
+export interface DiveOutput {
+    ms: number;
+    ease: string;
+    gOrigin: string;
+    lOrigin: string;
+    gEnd: string;
+    lStart: string;
+}
+/**
+ * Zooming in, the old picture flies past — the anchor grows to fill the screen —
+ * while the new one emerges from where that card sat. Zooming out is the exact
+ * inverse, which is why one pair of expressions covers both directions. That
+ * symmetry is the thing worth testing: it is easy to break one direction while
+ * the other still looks right.
+ */
+export declare function diveTransforms(input: DiveInput): DiveOutput;

package/dist/view/dive.js

@@ -0,0 +1,57 @@
+// The anchored dive, as arithmetic.
+//
+// Changing altitude animates about the one card the two views share, so the
+// reader never has to re-find their place (DESIGN §11, docs/notes/zoom-
+// transitions.md). All of the geometry lives here, taking four measured
+// rectangles and returning the transforms — no DOM, so it can be tested, and so
+// `scripts/hero-gif.mts` can re-derive the README animation from the same
+// constants instead of its own copy of them. Two copies in two languages with a
+// comment asserting they match is not a thing that stays true.
+//
+// It sat in `apps/spa/src/lib/` while the playground was the only thing that
+// zoomed. The interactive HTML export zooms too and is built by core, so this
+// moved here rather than becoming the second copy its own header warns about.
+/** How far the eye travels. Anything past ~3× reads as a jump cut, not a move. */
+export const CAP = 3.2;
+/** The incoming layer travels a fraction of the outgoing one — a full mirror
+ *  overshoots and feels like two separate animations played back to back. */
+export const TRAVEL = 0.62;
+/** The dive itself, and the anchorless fallback for a hop between two views at
+ *  the same altitude, where there is no shared card to travel through. */
+export const DIVE = { ms: 460, ease: "cubic-bezier(.32,.72,0,1)" };
+export const CUT = { ms: 240, ease: "cubic-bezier(.4,0,.2,1)" };
+export const centre = (b) => ({ x: b.x + b.w / 2, y: b.y + b.h / 2 });
+export const clamp = (v, lo, hi) => Math.min(hi, Math.max(lo, v));
+/** Scale factor for a dive through `anchor` within `view`, clamped both ways. */
+export const scaleFor = (view, anchor) => clamp(Math.min(view.w / anchor.w, view.h / anchor.h), 1.15, CAP);
+/**
+ * Zooming in, the old picture flies past — the anchor grows to fill the screen —
+ * while the new one emerges from where that card sat. Zooming out is the exact
+ * inverse, which is why one pair of expressions covers both directions. That
+ * symmetry is the thing worth testing: it is easy to break one direction while
+ * the other still looks right.
+ */
+export function diveTransforms(input) {
+    const { view, ghostBox, liveBox, anchor, dir } = input;
+    const { ms, ease } = anchor ? DIVE : CUT;
+    if (!anchor)
+        return { ms, ease, gOrigin: "50% 50%", lOrigin: "50% 50%", gEnd: "scale(.97)", lStart: "scale(1.03)" };
+    const k = scaleFor(view, anchor);
+    const kIn = 1 + (k - 1) * TRAVEL;
+    const A = centre(anchor), V = centre(view);
+    const dx = V.x - A.x, dy = V.y - A.y; // anchor centre → screen centre
+    const into = dir === "in";
+    const gPoint = into ? A : V;
+    const lPoint = into ? V : A;
+    return {
+        ms, ease,
+        gOrigin: `${gPoint.x - ghostBox.x}px ${gPoint.y - ghostBox.y}px`,
+        lOrigin: `${lPoint.x - liveBox.x}px ${lPoint.y - liveBox.y}px`,
+        gEnd: into
+            ? `translate(${dx}px, ${dy}px) scale(${k})`
+            : `translate(${-dx}px, ${-dy}px) scale(${1 / k})`,
+        lStart: into
+            ? `translate(${-dx}px, ${-dy}px) scale(${1 / kIn})`
+            : `translate(${dx}px, ${dy}px) scale(${kIn})`,
+    };
+}

package/dist/view/navigate.d.ts

@@ -0,0 +1,38 @@
+/** A view as a zoom target: what it is called, and the container it looks at. */
+export interface NavView {
+    name: string;
+    scope?: string;
+    title?: string;
+    auto?: boolean;
+}
+/**
+ * The one card that stands for `inner` inside a view scoped to `outer` — the
+ * element both altitudes have in common, and therefore the thing to anchor a
+ * zoom on. Undefined when the two scopes are not nested (a lateral hop), which
+ * is what makes the caller fall back to a cut rather than a dive.
+ */
+export declare function stepToward(outer: string | undefined, inner: string | undefined): string | undefined;
+/** The ancestor trail of a scope, outermost first — `a.b.c` → a, a.b, a.b.c. */
+export declare function ancestors(scope: string | undefined): string[];
+/** The scope one level out, or undefined at the top. */
+export declare function parentScope(scope: string | undefined): string | undefined;
+/** Zoom target for a clicked element: the view scoped to that container. */
+export declare function viewForPath(views: NavView[], activeView: string | undefined, path: string): NavView | undefined;
+/**
+ * How a move to `target` should be animated, derived from how the two scopes
+ * relate — never from which control was clicked, which is what makes the
+ * breadcrumb, the view tabs and a click on a card all behave the same. A
+ * lateral hop (same altitude, different lens) shares no card, so it comes back
+ * with no anchor and the caller cuts instead of diving.
+ */
+export declare function hop(views: NavView[], activeView: string | undefined, target: string): {
+    dir: "in" | "out";
+    anchor?: string;
+};
+/** Ancestor trail of the current scope, each hop a view we can jump to. */
+export declare function crumbs(views: NavView[], activeScope: string | undefined): {
+    label: string;
+    view?: string;
+}[];
+/** One altitude back up: the nearest ancestor that has a view of its own. */
+export declare function upView(views: NavView[], activeView: string | undefined, activeScope: string | undefined): string | undefined;

package/dist/view/navigate.js

@@ -0,0 +1,81 @@
+// Navigation arithmetic over dotted scope paths. Pure, and the thing that
+// decides zoom direction for every move between altitudes.
+//
+// Half of this was `apps/spa/src/lib/path.ts` and half was trapped inside
+// `App.tsx` as useMemos — fine while the playground was the only surface that
+// navigated. The interactive HTML export navigates too, and is built by core,
+// so it lives beside `resolve.ts` where the other pure view logic is: same
+// category (functions over the view set), same testability.
+//
+// One semantic to preserve exactly: `viewForPath` and `crumbs` both take the
+// FIRST view matching a scope. `examples/microservices` has three views scoped
+// to `orders` (`orders`, `orders-pci`, `checkout`), so clicking that card lands
+// on `orders` and the breadcrumb labels the hop `orders`. That is
+// declaration-order dependent and deliberately not "improved" here.
+/**
+ * The one card that stands for `inner` inside a view scoped to `outer` — the
+ * element both altitudes have in common, and therefore the thing to anchor a
+ * zoom on. Undefined when the two scopes are not nested (a lateral hop), which
+ * is what makes the caller fall back to a cut rather than a dive.
+ */
+export function stepToward(outer, inner) {
+    if (!inner)
+        return undefined;
+    if (!outer)
+        return inner.split(".")[0];
+    if (inner === outer || !inner.startsWith(`${outer}.`))
+        return undefined;
+    return `${outer}.${inner.slice(outer.length + 1).split(".")[0]}`;
+}
+/** The ancestor trail of a scope, outermost first — `a.b.c` → a, a.b, a.b.c. */
+export function ancestors(scope) {
+    if (!scope)
+        return [];
+    const parts = scope.split(".");
+    return parts.map((_, i) => parts.slice(0, i + 1).join("."));
+}
+/** The scope one level out, or undefined at the top. */
+export function parentScope(scope) {
+    if (!scope || !scope.includes("."))
+        return undefined;
+    return scope.slice(0, scope.lastIndexOf("."));
+}
+/** Zoom target for a clicked element: the view scoped to that container. */
+export function viewForPath(views, activeView, path) {
+    return views.find((v) => v.scope === path && v.name !== activeView);
+}
+/**
+ * How a move to `target` should be animated, derived from how the two scopes
+ * relate — never from which control was clicked, which is what makes the
+ * breadcrumb, the view tabs and a click on a card all behave the same. A
+ * lateral hop (same altitude, different lens) shares no card, so it comes back
+ * with no anchor and the caller cuts instead of diving.
+ */
+export function hop(views, activeView, target) {
+    const from = views.find((v) => v.name === activeView)?.scope;
+    const to = views.find((v) => v.name === target)?.scope;
+    const down = stepToward(from, to);
+    if (down)
+        return { dir: "in", anchor: down };
+    const up = stepToward(to, from);
+    if (up)
+        return { dir: "out", anchor: up };
+    return { dir: "in" };
+}
+/** Ancestor trail of the current scope, each hop a view we can jump to. */
+export function crumbs(views, activeScope) {
+    const trail = [];
+    const root = views.find((v) => !v.scope);
+    if (root)
+        trail.push({ label: "landscape", view: root.name });
+    if (!activeScope)
+        return trail;
+    const parts = activeScope.split(".");
+    for (const [i, path] of ancestors(activeScope).entries())
+        trail.push({ label: parts[i], view: views.find((v) => v.scope === path)?.name });
+    return trail;
+}
+/** One altitude back up: the nearest ancestor that has a view of its own. */
+export function upView(views, activeView, activeScope) {
+    return [...crumbs(views, activeScope)].reverse().find((c) => c.view && c.view !== activeView)?.view;
+}

package/dist/view/resolve.d.ts

@@ -0,0 +1,92 @@
+import type { Diagnostic, EdgeAnimate, Hue, SModel, SView } from "../model/types.js";
+export interface VNode {
+    path: string;
+    /** `person` is a leaf the restyle draws differently (a solid actor tile, no
+     *  border): the initiating human is not a service, and the shape says so
+     *  before the icon does. Context keeps the muted leaf treatment either way —
+     *  a periphery card is scenery, and scenery does not need a second shape. */
+    kind: "leaf" | "person" | "card" | "context-card" | "context-leaf";
+    label: string;
+    icon?: {
+        pack: string;
+        id: string;
+    };
+    glyph?: {
+        pack: string;
+        id: string;
+    };
+    /** Vendor mark composited onto the icon plate's corner (leaf nodes) — the
+     *  licence-clean vocabulary for platforms with no icon pack (SPEC §nodes). */
+    badge?: {
+        pack: string;
+        id: string;
+    };
+    tagline?: string;
+    preview: {
+        pack: string;
+        id: string;
+    }[];
+    /** Leaves beyond the ones `preview` shows — the shelf's `+N`. Counted from
+     *  the icons that would have been drawn, so it never claims more than the
+     *  strip actually left out. */
+    more?: number;
+    /** A short ownership label for the card's shelf: the team, domain or
+     *  namespace a system belongs to (`domain: "payments"`). Free text. */
+    domain?: string;
+    tags: string[];
+    /** someone else's system — DESIGN §3's hatched surface. A property of the
+     *  thing itself, so a container carries it for its whole card. */
+    external?: boolean;
+    description?: string;
+    frame?: string;
+    /** Effective hue: the view's `color #tag` if one matches, else the element's
+     *  own `color:`. Context cards ignore it — scenery stays muted. */
+    color?: Hue;
+}
+export interface VFrame {
+    path: string;
+    label: string;
+    /** Immediate enclosing frame — same field, same meaning as `VNode.frame`.
+     *  Only `expand *` produces it: explicit expands never nest (SPEC §5). */
+    frame?: string;
+    /** Same resolution as `VNode.color`; drawn as the frame's stroke. */
+    color?: Hue;
+}
+export interface VEdge {
+    id: string;
+    from: string;
+    to: string;
+    label?: string;
+    async: boolean;
+    /** Which animation, if any (SPEC §edges). Async edges default to `flow`
+     *  unless `animate: false`; sync edges are still unless they opt in. */
+    animate?: EdgeAnimate;
+    /** Dash pattern beyond each arrow's default: async is dashed already, so
+     *  only `dotted` changes it; sync edges can declare either. */
+    style?: "dashed" | "dotted";
+    count: number;
+    /** Effective tags. An aggregate carries the union of what it merged, so a
+     *  lens over a tag still finds the trunk that hides a tagged edge inside it. */
+    tags: string[];
+    /** Effective hue (view `color #tag` over the edge's own `color:`). A trunk
+     *  keeps one only when every member agrees, like `animate`/`style`. */
+    color?: Hue;
+    /** Which ends get an arrowhead: `->`/`~>` one, `<->` both, `--` none. The
+     *  view graph used to reduce every arrow to `async: boolean`, so two of the
+     *  four kinds the grammar accepts drew as a plain one-way arrow. */
+    heads: "one" | "both" | "none";
+}
+export interface ViewGraph {
+    nodes: VNode[];
+    edges: VEdge[];
+    frames: VFrame[];
+    /** `show flow` badges: edge id → step numbers (a lifted edge can carry
+     *  several); numbering is the flow's own — steps hidden at this altitude
+     *  keep their numbers out of the sequence, truthfully. */
+    flow?: {
+        label: string;
+        byEdge: Record<string, number[]>;
+    };
+    diagnostics: Diagnostic[];
+}
+export declare function resolveView(model: SModel, view: SView): ViewGraph;