@squinch/core 0.1.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 the Squinch authors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,41 @@
+@squinch/core
+Copyright 2026 the Squinch authors
+
+Licensed under the Apache License, Version 2.0 (see LICENSE).
+
+--------------------------------------------------------------------------------
+Bundled fonts
+--------------------------------------------------------------------------------
+
+This package ships font data, and those files are NOT under Apache-2.0:
+
+  fonts/inter-400.ttf, fonts/inter-500.ttf, fonts/inter-600.ttf
+  and the same faces embedded as woff2 data-URIs inside dist/
+
+      Inter, Copyright 2016 The Inter Project Authors
+      (https://github.com/rsms/inter), licensed under the SIL Open Font
+      License, Version 1.1.
+
+  fonts/mono-400.ttf
+  and the same face embedded as a woff2 data-URI inside dist/
+
+      IBM Plex Mono, Copyright 2017 IBM Corp.
+      (https://github.com/IBM/plex), licensed under the SIL Open Font
+      License, Version 1.1.
+
+Both are subsetted, not modified in outline. The OFL requires this notice to
+travel with the font data, which is why it is in the published package and not
+only in the repository.
+
+Rendered SVGs embed these faces so that a viewer draws the exact font the
+layout was measured against — see the "Text metrics never come from the
+environment" rule in CLAUDE.md.
+
+--------------------------------------------------------------------------------
+Icon artwork
+--------------------------------------------------------------------------------
+
+This package depends on @squinch/pack-aws, -azure, -k8s, -logos and -sys. Their
+artwork is third-party and carries its own terms — AWS's is no-derivatives and
+Microsoft's is limited to architecture diagrams, training and documentation.
+Each pack ships its own NOTICE with the full text; none of it is Apache-2.0.

package/dist/api.d.ts

@@ -0,0 +1,91 @@
+import { buildModel, buildProject, formatDiagnostics, type ProjectFile } from "./model/build.js";
+import { layoutView } from "./layout/layout.js";
+import { renderSVG } from "./render/svg.js";
+export { allFaces, fontFaceCSS } from "./render/svg.js";
+import { validateSVG } from "./render/validate.js";
+import { themes } from "./themes/index.js";
+import { allPackNames, iconIds, iconMeta, iconExists, packExists, iconTitle } from "./model/packs.js";
+import { diffModels, formatDiff, formatDiffMarkdown } from "./diff/diff.js";
+import type { Diagnostic } from "./model/types.js";
+export { buildModel, buildProject, formatDiagnostics, layoutView, renderSVG, validateSVG, themes };
+export { normalizeSource } from "./model/source.js";
+export { allPackNames, iconIds, iconMeta, iconExists, packExists, iconTitle };
+export { diffModels, formatDiff, formatDiffMarkdown };
+export * from "./view/navigate.js";
+export * from "./view/dive.js";
+export { exportHTML } from "./render/html.js";
+export type { HTMLExportOpts, HTMLExportResult } from "./render/html.js";
+export type { Change, ChangeKind, DiffResult, Weight } from "./diff/diff.js";
+/** Diff two projects by source — the common entry point. */
+export declare function diffProjects(before: ProjectFile[], after: ProjectFile[]): import("./diff/diff.js").DiffResult;
+/** Every icon a source references — preload these before rendering in a browser. */
+export declare function iconsUsedBy(files: ProjectFile[] | string): {
+    pack: string;
+    id: string;
+}[];
+/** Icon search across installed packs — powers `squinch icons search`.
+ *
+ *  Matches every whitespace-separated word of the query against the id *and*
+ *  the human title, treating `-` as a space. A raw substring test against the
+ *  id alone is what shipped, and it failed on the most natural query anyone
+ *  types: "front door", "key vault", "api management", "container registry"
+ *  and "data factory" all returned nothing while the icons were right there.
+ *
+ *  A canonical id and its alias never both appear — one icon, one row. Callers
+ *  that want to *show* the short forms (the CLI does, because SKILL.md teaches
+ *  them and a result of only `azure/key-vaults` reads as proof that
+ *  `azure/key-vault` doesn't exist) can look them up via `packInfo`. */
+export declare function searchIcons(query: string, pack?: string): string[];
+export type { ProjectFile };
+export type * from "./model/types.js";
+export { HUES } from "./model/types.js";
+export { hueOf } from "./themes/index.js";
+export type { Positioned } from "./layout/layout.js";
+export type { Theme } from "./themes/index.js";
+export interface RenderResult {
+    svg?: string;
+    diagnostics: Diagnostic[];
+    ok: boolean;
+    /** Present when the view shows a flow. `steps` counts the hops that actually
+     *  render *at this altitude* — a step whose endpoints both lift into one card
+     *  has nothing to draw — so it is the real length of the story, and the bound
+     *  a viewer should step to. */
+    flow?: {
+        label: string;
+        steps: number;
+    };
+}
+/** Views a source declares, with the container each one scopes to (zoom targets). */
+export declare function viewIndex(src: string): {
+    name: string;
+    scope?: string;
+    title?: string;
+    auto?: boolean;
+}[];
+/** One-call pipeline: source → SVG for a view (default: first/implicit view). */
+export declare function render(src: string, opts?: {
+    view?: string;
+    theme?: string;
+    embedFonts?: boolean;
+    flowStep?: number;
+    /** Emit one file carrying both palettes, switched by `prefers-color-scheme`
+     *  — for embedding somewhere you do not control the background. Requires a
+     *  theme with a `pairsWith` counterpart. */
+    adaptive?: boolean;
+}): Promise<RenderResult>;
+/** Multi-file project pipeline: files merge into one model namespace (SPEC §2). */
+export declare function renderProject(input: ProjectFile[], opts?: {
+    view?: string;
+    theme?: string;
+    embedFonts?: boolean;
+    flowStep?: number;
+    /** Emit one file carrying both palettes, switched by `prefers-color-scheme`
+     *  — for embedding somewhere you do not control the background. Requires a
+     *  theme with a `pairsWith` counterpart. */
+    adaptive?: boolean;
+    /** Hoist shared definitions out of this SVG — see `RenderOpts.collectDefs`.
+     *  Used by the interactive HTML export, where every view shares a document
+     *  and therefore one set of defs. */
+    collectDefs?: Map<string, string>;
+    defsScope?: string;
+}): Promise<RenderResult>;

package/dist/api.js

@@ -0,0 +1,232 @@
+// The pipeline itself: parse → model → layout → render. No host-specific I/O —
+// see index.ts (Node) and browser.ts for how packs get registered.
+import { buildModel, buildProject, formatDiagnostics } from "./model/build.js";
+import { normalizeFiles } from "./model/source.js";
+import { layoutView } from "./layout/layout.js";
+import { renderSVG } from "./render/svg.js";
+// the bundled face inventory — the HTML export hoists it, tests assert against it
+export { allFaces, fontFaceCSS } from "./render/svg.js";
+import { validateSVG } from "./render/validate.js";
+import { mergeAdaptive } from "./render/adaptive.js";
+import { themes } from "./themes/index.js";
+import { allPackNames, iconIds, iconMeta, iconExists, packExists, iconTitle } from "./model/packs.js";
+import { packInfo } from "./packs/registry.js";
+import { diffModels, formatDiff, formatDiffMarkdown } from "./diff/diff.js";
+import { suggest } from "./model/suggest.js";
+export { buildModel, buildProject, formatDiagnostics, layoutView, renderSVG, validateSVG, themes };
+// CRLF → LF, exported for hosts that map core's Loc offsets back into their own
+// buffer: normalize that buffer first, or the positions are off by one per line
+// on a Windows checkout (packages/vscode/src/features.ts is the one that does).
+export { normalizeSource } from "./model/source.js";
+// pack introspection — the editor tooling needs the same view of packs
+// the compiler has (completion lists, hovers, validation).
+export { allPackNames, iconIds, iconMeta, iconExists, packExists, iconTitle };
+// semantic diff (SPEC §diff): model comparison, no layout involved
+export { diffModels, formatDiff, formatDiffMarkdown };
+// altitude navigation (DESIGN §11): scope arithmetic and the dive geometry.
+// Pure, and shared — the playground and the interactive export must perform
+// the same motion, so neither owns a copy of it.
+export * from "./view/navigate.js";
+export * from "./view/dive.js";
+// the interactive export: every view of a project in one self-contained file
+export { exportHTML } from "./render/html.js";
+/** Diff two projects by source — the common entry point. */
+export function diffProjects(before, after) {
+    return diffModels(buildProject(before).model, buildProject(after).model);
+}
+/** Every icon a source references — preload these before rendering in a browser. */
+export function iconsUsedBy(files) {
+    const project = typeof files === "string" ? [{ name: "input", src: files }] : files;
+    const { model } = buildProject(project);
+    const refs = new Map();
+    for (const n of model.nodes.values()) {
+        if (n.icon)
+            refs.set(`${n.icon.pack}/${n.icon.id}`, n.icon);
+        const b = n.attrs["badge"];
+        if (b?.includes("/"))
+            refs.set(b, { pack: b.split("/")[0], id: b.split("/")[1] });
+    }
+    for (const z of model.zones)
+        if (z.icon)
+            refs.set(`${z.icon.pack}/${z.icon.id}`, z.icon);
+    for (const c of model.containers.values()) {
+        const g = c.attrs["glyph"];
+        if (g?.includes("/"))
+            refs.set(g, { pack: g.split("/")[0], id: g.split("/")[1] });
+    }
+    return [...refs.values()];
+}
+/** Icon search across installed packs — powers `squinch icons search`.
+ *
+ *  Matches every whitespace-separated word of the query against the id *and*
+ *  the human title, treating `-` as a space. A raw substring test against the
+ *  id alone is what shipped, and it failed on the most natural query anyone
+ *  types: "front door", "key vault", "api management", "container registry"
+ *  and "data factory" all returned nothing while the icons were right there.
+ *
+ *  A canonical id and its alias never both appear — one icon, one row. Callers
+ *  that want to *show* the short forms (the CLI does, because SKILL.md teaches
+ *  them and a result of only `azure/key-vaults` reads as proof that
+ *  `azure/key-vault` doesn't exist) can look them up via `packInfo`. */
+export function searchIcons(query, pack) {
+    // Vendors are inconsistent about number — Azure has "Container Registries"
+    // and "Data Factories" where everyone searches "container registry" and
+    // "data factory" — so both sides are singularized before comparing.
+    // Short words are left alone: stemming `sqs` to `sq` makes it match the `sq`
+    // inside `postgresql`, and acronyms are exactly what people search by.
+    const stem = (w) => w.length < 5 ? w
+        : w.endsWith("ies") ? `${w.slice(0, -3)}y`
+            : w.endsWith("s") ? w.slice(0, -1)
+                : w;
+    const norm = (s) => s.toLowerCase().split(/[\s-]+/).filter(Boolean).map(stem).join(" ");
+    // A query word that names an installed pack is a filter, not a search term:
+    // `sys` should list the sys glyphs and `logos stripe` should look inside
+    // logos — matching the literal letters instead surfaced azure's
+    // `defender-…-system` rows while the pack itself stayed invisible, which
+    // read as "there are no sys icons". Detected on the raw words, before
+    // stemming turns `logos` into `logo`; an explicit `pack` argument wins, and
+    // the word then stays an ordinary term. With no terms left, every icon in
+    // the pack matches — the browsing listing that motivated this.
+    let packFilter = pack;
+    let rawWords = query.toLowerCase().split(/[\s-]+/).filter(Boolean);
+    if (!packFilter) {
+        const packWord = rawWords.find((w) => allPackNames().includes(w));
+        if (packWord) {
+            packFilter = packWord;
+            rawWords = rawWords.filter((w) => w !== packWord);
+        }
+    }
+    const words = rawWords.map(stem);
+    const hits = [];
+    for (const name of allPackNames()) {
+        if (packFilter && name !== packFilter)
+            continue;
+        const aliases = packInfo(name)?.aliases ?? {};
+        const haystack = (id) => norm(`${id} ${iconTitle(name, id) ?? ""}`);
+        const matched = new Set(iconIds(name).filter((id) => words.every((w) => haystack(id).includes(w))));
+        for (const id of [...matched].sort()) {
+            if (aliases[id] && matched.has(aliases[id]))
+                continue; // canonical covers it
+            hits.push(`${name}/${id}`);
+        }
+    }
+    return hits.sort();
+}
+// the one colour vocabulary, for editors that complete it and tests that sweep it
+export { HUES } from "./model/types.js";
+export { hueOf } from "./themes/index.js";
+/** Views a source declares, with the container each one scopes to (zoom targets). */
+export function viewIndex(src) {
+    const { model } = buildModel(src);
+    return model.views.map((v) => ({ name: v.name, scope: v.scope, title: v.title, auto: v.auto }));
+}
+/** One-call pipeline: source → SVG for a view (default: first/implicit view). */
+export async function render(src, opts = {}) {
+    return renderProject([{ name: "input", src }], opts);
+}
+/** Multi-file project pipeline: files merge into one model namespace (SPEC §2). */
+export async function renderProject(input, opts = {}) {
+    // Normalized here as well as inside buildProject: this is a public entry
+    // point, so anything it derives from the source text — today the model, and
+    // whatever a later render option reads — sees LF regardless of how the file
+    // was checked out (model/source.ts). Idempotent, so the second pass is free.
+    const files = normalizeFiles(input);
+    const built = buildProject(files);
+    if (!built.ok)
+        return { diagnostics: built.diagnostics, ok: false };
+    let view = opts.view
+        ? built.model.views.find((v) => v.name === opts.view)
+        : built.model.views[0];
+    // A view name that doesn't exist used to fall through to the implicit default
+    // below: a *different* diagram, rendered successfully, exit 0. In an agent
+    // loop driven by exit codes that is the worst possible failure — a typo buys
+    // you a plausible picture with none of your view's settings.
+    if (opts.view && !view) {
+        const names = built.model.views.map((v) => v.name);
+        return {
+            diagnostics: [
+                ...built.diagnostics,
+                {
+                    severity: "error",
+                    message: `unknown view \`${opts.view}\``,
+                    fix: names.length
+                        ? ((m) => (m ? `did you mean \`${m}\`? ` : "") + `views: ${names.join(", ")}`)(suggest(opts.view, names))
+                        : "this project declares no views",
+                    loc: { from: 0, to: 0, line: 1, col: 1 },
+                },
+            ],
+            ok: false,
+        };
+    }
+    if (!view) {
+        // implicit default view: everything (auto view of sole top-level container)
+        const first = [...built.model.containers.keys()][0];
+        view = {
+            name: first ?? "default", scope: first,
+            only: [], include: [], includeStar: false, exclude: [], expand: [], expandStar: false, detail: [],
+            context: "auto", highlight: [], colors: [], showDescriptions: false, legend: false, notes: [],
+            layout: { place: [], routes: [], align: [], channels: [] },
+            loc: { from: 0, to: 0, line: 1, col: 1 },
+        };
+    }
+    const themeName = opts.theme ?? view.theme ?? built.model.fileTheme ?? "light";
+    const theme = themes[themeName];
+    const diagnostics = [...built.diagnostics];
+    if (!theme)
+        return {
+            diagnostics: [...diagnostics, {
+                    severity: "error",
+                    message: `unknown theme \`${themeName}\``,
+                    fix: `available: ${Object.keys(themes).join(", ")}`,
+                    loc: view.loc,
+                }],
+            ok: false,
+        };
+    const { positioned, diagnostics: layoutDiags } = await layoutView(built.model, view, theme.font);
+    diagnostics.push(...layoutDiags);
+    if (diagnostics.some((d) => d.severity === "error"))
+        return { diagnostics, ok: false };
+    const flow = positioned.flow
+        ? {
+            label: positioned.flow.label,
+            // distinct hops that render *here*, which is what `flowStep` counts
+            steps: new Set(Object.values(positioned.flow.byEdge).flat()).size,
+        }
+        : undefined;
+    // One geometry, drawn once per palette. Layout depends on the theme only
+    // through its font, and an adaptive pair shares that font — so both draws
+    // come off the same `positioned` and cannot disagree about anything but
+    // colour. That is what makes folding them into one file safe.
+    const draw = (th) => renderSVG(positioned, th, {
+        highlight: view.highlight,
+        colors: view.colors,
+        notes: view.notes,
+        showDescriptions: view.showDescriptions,
+        legend: view.legend,
+        titleblock: view.titleblock,
+        title: view.title,
+        embedFonts: opts.embedFonts,
+        flowStep: opts.flowStep,
+        collectDefs: opts.collectDefs,
+        defsScope: opts.defsScope,
+    });
+    let svg = draw(theme);
+    if (opts.adaptive) {
+        const pair = theme.pairsWith ? themes[theme.pairsWith] : undefined;
+        if (!pair) {
+            const pairable = Object.values(themes).filter((x) => x.pairsWith).map((x) => x.name);
+            return {
+                diagnostics: [...diagnostics, {
+                        severity: "error",
+                        message: `theme \`${themeName}\` has no dark counterpart to pair with`,
+                        fix: "an adaptive SVG is a light theme carrying a dark override; " +
+                            `render one of: ${pairable.join(", ")}`,
+                        loc: view.loc,
+                    }],
+                ok: false,
+            };
+        }
+        svg = mergeAdaptive(svg, draw(pair));
+    }
+    return { svg, diagnostics, ok: true, ...(flow ? { flow } : {}) };
+}

package/dist/browser.d.ts

@@ -0,0 +1,3 @@
+export * from "./api.js";
+export { registerPack, preloadIcons, packInfo, iconIds, hasIcon, glyph } from "./packs/registry.js";
+export type { PackManifest, AssetLoader } from "./packs/registry.js";

package/dist/browser.js

@@ -0,0 +1,9 @@
+// Browser entry: everything from the core pipeline, minus the Node pack source.
+// Hosts register packs themselves:
+//
+//   import { registerPack, preloadIcons, render } from "@squinch/core/browser";
+//   registerPack(manifest, (file) => fetch(`/icons/${file}`).then(r => r.text()));
+//   await preloadIcons(iconsUsedBy(source));
+//   const { svg } = await render(source, { view, theme });
+export * from "./api.js";
+export { registerPack, preloadIcons, packInfo, iconIds, hasIcon, glyph } from "./packs/registry.js";

package/dist/diff/diff.d.ts

@@ -0,0 +1,30 @@
+import type { SModel } from "../model/types.js";
+export type ChangeKind = "added" | "removed" | "changed";
+export type Weight = "structural" | "cosmetic";
+export interface Change {
+    kind: ChangeKind;
+    weight: Weight;
+    /** what sort of thing changed — node, edge, zone… */
+    subject: "system" | "container" | "node" | "edge" | "zone" | "flow" | "view";
+    /** stable identity of the thing (path, edge signature, view name…) */
+    id: string;
+    /** one-line human summary */
+    detail: string;
+    /** set on `changed`: what it was, and what it now is */
+    before?: string;
+    after?: string;
+    /** `possible rename of x` — a hint, never an assumption */
+    note?: string;
+}
+export interface DiffResult {
+    changes: Change[];
+    structural: number;
+    cosmetic: number;
+    /** true when the two models are semantically identical */
+    same: boolean;
+}
+export declare function diffModels(before: SModel, after: SModel): DiffResult;
+/** Human-readable report, grouped by weight. */
+export declare function formatDiff(d: DiffResult): string;
+/** Markdown for a PR comment. */
+export declare function formatDiffMarkdown(d: DiffResult): string;