@pcbjs/cli 0.0.0 → 0.0.1-next.9029beb783788cfbb471cc9d57e1b47864c6eaa6

package/dist/doctor.js

@@ -0,0 +1,151 @@
+import { existsSync, readFileSync, readdirSync, realpathSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { ROUTER_VERSION } from '@pcbjs/compile/route-cache';
+import { TUNE_VERSION } from '@pcbjs/compile/tune';
+import { REFERENCE_VERSION } from './references.js';
+import { findChrome } from './shot.js';
+import { findConfig, resolveConfig } from './config.js';
+import { installedModels } from '@pcbjs/kicad';
+import { fetchedDir, KICAD_3D_TAG } from './fetch-model.js';
+/** The editor extension, which ships inside @pcbjs/cli and is versioned on its own. */
+const UNVERSIONED = new Set(['@pcbjs/vscode']);
+const cliDir = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+export function cliVersion() {
+    try {
+        return JSON.parse(readFileSync(join(cliDir, 'package.json'), 'utf8')).version;
+    }
+    catch {
+        return '0.0.0';
+    }
+}
+/** The dist-tag a version is published under: beta for 0.0.1-beta.2, next for a snapshot, else latest. */
+export function distTag(version) {
+    return /^\d+\.\d+\.\d+-([A-Za-z]+)/.exec(version)?.[1] ?? 'latest';
+}
+/** What a new project asks for: a caret on a prerelease also takes next snapshots, so the tag; else the minor a train shares. */
+export function installRange(version) {
+    const tag = distTag(version);
+    return tag === 'latest' ? `~${version.split('.').slice(0, 2).join('.')}.0` : tag;
+}
+/** latest holds the 0.0.0 placeholder while the packages are in beta, so the fix names the running line. */
+export const UPDATE_COMMAND = `npm install @pcbjs/pcbjs@${distTag(cliVersion())}`;
+/** Every @pcbjs package a project resolves, nearest node_modules first, as Node resolves them. */
+export function installedPackages(root) {
+    const found = new Map();
+    for (let dir = resolve(root);; dir = dirname(dir)) {
+        const scope = join(dir, 'node_modules', '@pcbjs');
+        if (existsSync(scope))
+            for (const sub of readdirSync(scope).sort()) {
+                const name = `@pcbjs/${sub}`;
+                const pkgFile = join(scope, sub, 'package.json');
+                if (found.has(name) || !existsSync(pkgFile))
+                    continue;
+                try {
+                    found.set(name, { name, version: JSON.parse(readFileSync(pkgFile, 'utf8')).version, dir: join(scope, sub) });
+                }
+                catch { }
+            }
+        if (dirname(dir) === dir)
+            break;
+    }
+    return [...found.values()].sort((a, b) => a.name.localeCompare(b.name));
+}
+/** major.minor, so 0.0.1 and 0.0.2 agree and 0.1.0-beta.1 and 0.1.3 agree. */
+export function minorOf(version) {
+    const m = /^(\d+)\.(\d+)/.exec(version);
+    return m ? `${m[1]}.${m[2]}` : version;
+}
+/** Null when every package shares one major.minor, else the line naming each version and the fix. */
+export function versionSkew(packages) {
+    packages = packages.filter(p => !UNVERSIONED.has(p.name));
+    const minors = new Set(packages.map(p => minorOf(p.version)));
+    if (minors.size < 2)
+        return null;
+    const list = packages.map(p => `${p.name} ${p.version}`).join(', ');
+    return `@pcbjs packages disagree on the version: ${list}; run ${UPDATE_COMMAND}`;
+}
+/** The installed packages plus the running CLI when it is another copy, such as a global install. */
+export function packagesInUse(root) {
+    const installed = installedPackages(root);
+    const own = installed.find(p => p.name === '@pcbjs/cli');
+    if (own && realpathSync(own.dir) === realpathSync(cliDir))
+        return installed;
+    return [...installed, { name: 'pcbjs (running)', version: cliVersion(), dir: cliDir }];
+}
+const KEY = Symbol.for('pcbjs.cli.versionWarned');
+/** The single warning line for a version skew, printed at most once per process. */
+export function warnVersionSkew(root = process.cwd(), warn = l => console.warn(l)) {
+    const g = globalThis;
+    if (g[KEY])
+        return;
+    g[KEY] = true;
+    try {
+        const skew = versionSkew(packagesInUse(root));
+        if (skew)
+            warn(`pcbjs: warning: ${skew}`);
+    }
+    catch { }
+}
+export function stepConverter() {
+    try {
+        const step = createRequire(import.meta.url).resolve('@pcbjs/step/package.json');
+        const occt = createRequire(step).resolve('occt-import-js');
+        const wasm = join(dirname(occt), 'occt-import-js.wasm');
+        return existsSync(wasm) ? wasm : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Model files under a folder, its LICENSES.md left out. */
+function countFiles(dir) {
+    try {
+        return readdirSync(dir, { recursive: true, withFileTypes: true }).filter(e => e.isFile() && e.name !== 'LICENSES.md' && !e.name.endsWith('.tmp')).length;
+    }
+    catch {
+        return 0;
+    }
+}
+export async function doctor(o = {}) {
+    const root = resolve(o.root ?? process.cwd());
+    const log = o.log ?? (l => console.log(l));
+    const show = (p) => (relative(root, p).startsWith('..') ? p : relative(root, p) || '.');
+    const row = (k, v) => log(`${k.padEnd(18)} ${v}`);
+    const packages = packagesInUse(root);
+    row('pcbjs', `${cliVersion()}  ${show(cliDir)}`);
+    row('node', process.version);
+    if (!packages.length)
+        row('packages', `none under ${root}; run npm install`);
+    for (const p of packages)
+        row(p.name, `${p.version}  ${show(p.dir)}`);
+    const chrome = findChrome();
+    row('chrome', chrome ?? 'not found; pcbjs shot needs one, set PCBJS_CHROME');
+    const wasm = stepConverter();
+    row('step converter', wasm ? show(wasm) : 'not found; STEP models will not load, reinstall @pcbjs/step');
+    row('formats', `router ${ROUTER_VERSION}, tune ${TUNE_VERSION}, reference ${REFERENCE_VERSION}`);
+    const found = o.config ? { file: resolve(root, o.config) } : findConfig(root);
+    if (!found)
+        row('config', 'none; pcbjs create <dir> starts a project');
+    else {
+        row('config', show(found.file));
+        try {
+            const cfg = await resolveConfig([], 'build', o.config, root, () => { });
+            row('entries', cfg.entries.map(e => e.rel).join(', '));
+            const lib = installedModels();
+            row('kicad models', lib && existsSync(lib) ? show(lib) : `none installed; kicad: models download from KiCad ${KICAD_3D_TAG} on first use`);
+            row('fetched models', `${countFiles(fetchedDir(cfg.root))} in ${show(fetchedDir(cfg.root))}; pcbjs model check counts the standard library's parts`);
+        }
+        catch (e) {
+            row('entries', `error: ${e.message.split('\n')[0]}`);
+        }
+    }
+    const skew = versionSkew(packages);
+    if (skew) {
+        log(`\nerror: ${skew}`);
+        return 1;
+    }
+    log('\nversions agree');
+    return 0;
+}

package/dist/drafts.d.ts

@@ -0,0 +1,47 @@
+import { type Plugin } from 'vite';
+export interface Span {
+    start: number;
+    end: number;
+}
+export interface Draft {
+    /** the file as the editor names it, which may be through a symbolic link */
+    named: string;
+    /** the editor's text */
+    text: string;
+    /** what Vite compiles: the text, or its repair */
+    code: string;
+    /** the spans the repair blanked, offsets of `text` */
+    skipped: Span[];
+    /** where the repair's closers start: an offset at or past it maps to the one before */
+    limit: number | null;
+    /** neither the text nor a repair compiles: the last good board stays */
+    broken: boolean;
+}
+export interface Drafts {
+    /** the editor's text of a file, applied after a pause in typing; null drops the draft at once */
+    set(file: string, text: string | null, named?: string): void;
+    get(file: string): Draft | undefined;
+    files(): string[];
+    dispose(): void;
+}
+/** The drafts of a dev server; `changed` runs once a file's draft is applied or dropped. */
+export declare function drafts(changed: (file: string) => void, delayMs?: number): Drafts;
+/** The offset of the first syntax error esbuild finds, null when it takes the code. */
+export declare function syntaxError(file: string, code: string): Promise<number | null>;
+/** The draft of a text: as it is when esbuild takes it, else the repair, retried once with the offset esbuild still rejects. */
+export declare function prepare(file: string, text: string): Promise<Omit<Draft, 'named'>>;
+/** Serve each draft in place of its file. */
+export declare function draftsPlugin(store: () => Drafts | null | undefined): Plugin;
+interface Position {
+    line: number;
+    character: number;
+}
+/** The spans each draft's repair skipped, as LSP ranges of the editor's text. */
+export declare function skippedRanges(store: Drafts | null | undefined): {
+    file: string;
+    ranges: {
+        start: Position;
+        end: Position;
+    }[];
+}[];
+export {};

package/dist/drafts.js

@@ -0,0 +1,113 @@
+// docs/editor.md, Drafts, has the rules.
+import { readFileSync } from 'node:fs';
+import { transformWithEsbuild } from 'vite';
+import { loadLsp } from './lsp.js';
+/** The drafts of a dev server; `changed` runs once a file's draft is applied or dropped. */
+export function drafts(changed, delayMs = 200) {
+    const map = new Map();
+    const timers = new Map();
+    const seq = new Map();
+    const apply = async (file, text, named, n) => {
+        let disk = null;
+        try {
+            disk = readFileSync(file, 'utf8');
+        }
+        catch { /* a file not saved yet */ }
+        const d = text === null || text === disk ? null : { ...(await prepare(file, text)), named };
+        if (seq.get(file) !== n)
+            return;
+        if (!d) {
+            if (map.delete(file))
+                changed(file);
+            return;
+        }
+        map.set(file, d);
+        changed(file);
+    };
+    return {
+        set(file, text, named = file) {
+            const n = (seq.get(file) ?? 0) + 1;
+            seq.set(file, n);
+            clearTimeout(timers.get(file));
+            timers.delete(file);
+            if (text === null) {
+                void apply(file, null, named, n);
+                return;
+            }
+            timers.set(file, setTimeout(() => { timers.delete(file); void apply(file, text, named, n); }, delayMs));
+        },
+        get: file => map.get(file),
+        files: () => [...map.keys()],
+        dispose() {
+            for (const t of timers.values())
+                clearTimeout(t);
+            timers.clear();
+            map.clear();
+        },
+    };
+}
+const LOADERS = { ts: 'ts', mts: 'ts', cts: 'ts', tsx: 'tsx', js: 'js', mjs: 'js', cjs: 'js', jsx: 'jsx' };
+/** The offset of the first syntax error esbuild finds, null when it takes the code. */
+export async function syntaxError(file, code) {
+    const loader = LOADERS[file.split('.').pop() ?? ''] ?? 'ts';
+    try {
+        await transformWithEsbuild(code, file, { loader, jsx: 'automatic', tsconfigRaw: {} });
+        return null;
+    }
+    catch (e) {
+        const at = e?.errors?.[0]?.location;
+        if (!at)
+            return 0;
+        const lines = code.split('\n');
+        const start = lines.slice(0, at.line - 1).reduce((n, l) => n + l.length + 1, 0);
+        // esbuild counts columns in UTF-8 bytes
+        return start + Buffer.from(lines[at.line - 1] ?? '').subarray(0, at.column).toString().length;
+    }
+}
+/** The draft of a text: as it is when esbuild takes it, else the repair, retried once with the offset esbuild still rejects. */
+export async function prepare(file, text) {
+    const err = await syntaxError(file, text);
+    if (err === null)
+        return { text, code: text, skipped: [], limit: null, broken: false };
+    const { repair } = await loadLsp();
+    let r = repair(text, file);
+    let left = r.ok ? await syntaxError(file, r.text) : -1;
+    if (left !== null && left >= 0) {
+        r = repair(text, file, [Math.min(left, text.length)]);
+        left = r.ok ? await syntaxError(file, r.text) : -1;
+    }
+    if (left !== null)
+        return { text, code: text, skipped: [], limit: null, broken: true };
+    return { text, code: r.text, skipped: r.skipped, limit: r.limit, broken: false };
+}
+/** Serve each draft in place of its file. */
+export function draftsPlugin(store) {
+    return {
+        name: 'pcbjs:drafts',
+        enforce: 'pre',
+        load(id) {
+            return store()?.get(id.split('?')[0])?.code;
+        },
+    };
+}
+/** The spans each draft's repair skipped, as LSP ranges of the editor's text. */
+export function skippedRanges(store) {
+    const out = [];
+    for (const f of store?.files() ?? []) {
+        const d = store.get(f);
+        if (!d.skipped.length)
+            continue;
+        const starts = [0];
+        for (let i = 0; i < d.text.length; i++)
+            if (d.text.charCodeAt(i) === 10)
+                starts.push(i + 1);
+        const at = (o) => {
+            let line = 0;
+            while (line + 1 < starts.length && starts[line + 1] <= o)
+                line++;
+            return { line, character: o - starts[line] };
+        };
+        out.push({ file: d.named, ranges: d.skipped.map(s => ({ start: at(s.start), end: at(s.end) })) });
+    }
+    return out;
+}

package/dist/fetch-model-child.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/fetch-model-child.js

@@ -0,0 +1,12 @@
+// node fetch-model-child.js <root> <source>: downloads one model for a compile that needs it at once; exit 1 with the reason, 2 when the network is down.
+import { download } from './fetch-model.js';
+const [root, source] = process.argv.slice(2);
+try {
+    await download(root, source);
+    process.exit(0);
+}
+catch (e) {
+    const cause = e?.cause?.code ?? e?.cause?.message;
+    process.stderr.write(`${String(e?.message ?? e).split('\n')[0]}${cause ? `: ${cause}` : ''}\n`);
+    process.exit(e instanceof TypeError ? 2 : 1);
+}

package/dist/fetch-model.d.ts

@@ -0,0 +1,32 @@
+import { type RemoteModelResolver } from '@pcbjs/compile/models';
+/** The tag of KiCad's 3D library the stdlib's models are aligned against. */
+export declare const KICAD_3D_TAG = "10.0.7";
+export declare const fetchedDir: (root: string) => string;
+/** Where a fetched model is cached in a project. */
+export declare function fetchedPath(root: string, source: string): string;
+/** The download URL of a `kicad:` or https source. */
+export declare const sourceUrl: (source: string) => string;
+/** The licence line of a source, as far as its host says. */
+export declare function licenceOf(source: string): string;
+/** Append the source line of a model to <dir>/LICENSES.md, creating the file with its header. */
+export declare function noteSource(dir: string, file: string, source: string, date?: string): string;
+/** The STEP model of an LCSC part, no login: easyeda.com/api/products/<C-number>/components names it, modules.easyeda.com serves it. */
+export declare function lcscModel(code: string, fetcher?: typeof fetch): Promise<{
+    data: Uint8Array;
+    name: string;
+    url: string;
+    note: string;
+}>;
+/** Download a source into the project's cache, the file written whole or not at all, and note its licence. */
+export declare function download(root: string, source: string): Promise<string>;
+/** Forget the failures of this process, for `model fetch`. */
+export declare function retryFetches(): void;
+/** The resolver the compile calls for each fetched model: the installed KiCad library, the cache, or a download in a child process. */
+export declare function remoteResolver(root: string): RemoteModelResolver;
+/** One line for the parts of a board whose models did not download, once per process for the same parts. */
+export declare function fetchNotice(board: string, waiting: {
+    ref: string;
+    source: string;
+}[]): string | null;
+/** Let the next compile of this project resolve and fetch its models; the compile is synchronous, so each sets its own root. */
+export declare function installModelFetch(root: string): void;

package/dist/fetch-model.js

@@ -0,0 +1,177 @@
+import { spawnSync } from 'node:child_process';
+import { appendFileSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join, relative, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { kicadModel } from '@pcbjs/kicad';
+import { REMOTE_MODEL } from '@pcbjs/compile/models';
+/** The tag of KiCad's 3D library the stdlib's models are aligned against. */
+export const KICAD_3D_TAG = '10.0.7';
+const KICAD_RAW = `https://gitlab.com/kicad/libraries/kicad-packages3D/-/raw/${KICAD_3D_TAG}/`;
+const EASYEDA_MODELS = 'https://modules.easyeda.com/qAxj6KHrDKw4blvCG8QJPs7Y/';
+const KICAD_LICENCE = 'CC-BY-SA 4.0 with the KiCad library exception, https://www.kicad.org/libraries/license/';
+export const fetchedDir = (root) => join(root, '.pcbjs', 'models', 'fetched');
+const kicadPath = (source) => source.slice('kicad:'.length).replace(/\.wrl$/i, '.step');
+/** Where a fetched model is cached in a project. */
+export function fetchedPath(root, source) {
+    const dir = fetchedDir(root);
+    if (/^kicad:/i.test(source))
+        return join(dir, `kicad-${KICAD_3D_TAG}`, ...kicadPath(source).split('/'));
+    if (/^lcsc:/i.test(source))
+        return join(dir, 'lcsc', `${source.slice(5).toUpperCase()}.step`);
+    const u = new URL(source);
+    return join(dir, u.host, ...u.pathname.split('/').filter(Boolean).map(decodeURIComponent));
+}
+/** The download URL of a `kicad:` or https source. */
+export const sourceUrl = (source) => (/^kicad:/i.test(source) ? KICAD_RAW + kicadPath(source) : source);
+/** The licence line of a source, as far as its host says. */
+export function licenceOf(source) {
+    if (/^kicad:/i.test(source) || /gitlab\.com\/kicad\//.test(source))
+        return `KiCad 3D library ${KICAD_3D_TAG}, ${KICAD_LICENCE}`;
+    if (/github(usercontent)?\.com\/espressif\/kicad-libraries/.test(source))
+        return `Espressif KiCad library, ${KICAD_LICENCE}`;
+    if (/^lcsc:/i.test(source))
+        return 'EasyEDA library model for the LCSC part, no licence stated: for the 3D view, check the maker\'s terms before you share the file';
+    return 'licence not known: check the source before you share the file';
+}
+const LICENSES_HEAD = '# Model sources\n\nWhere each model file in this folder came from and when it was added. Check the licence of each source before you share or sell a design with the model: manufacturer models usually allow use in designs but not redistribution, and KiCad\'s packages3D models are CC-BY-SA 4.0 with an exception that lets designs and generated files use them freely.\n\n';
+/** Append the source line of a model to <dir>/LICENSES.md, creating the file with its header. */
+export function noteSource(dir, file, source, date = new Date().toISOString().slice(0, 10)) {
+    const md = join(dir, 'LICENSES.md');
+    const line = `- \`${file}\`: ${source}, added ${date}\n`;
+    const had = existsSync(md) ? readFileSync(md, 'utf8') : null;
+    if (had === null)
+        writeFileSync(md, LICENSES_HEAD + line);
+    else if (!had.includes(`\`${file}\`: ${source},`))
+        appendFileSync(md, (had.endsWith('\n') ? '' : '\n') + line);
+    return md;
+}
+/** The STEP model of an LCSC part, no login: easyeda.com/api/products/<C-number>/components names it, modules.easyeda.com serves it. */
+export async function lcscModel(code, fetcher = fetch) {
+    const c = code.toUpperCase();
+    if (!/^C\d+$/.test(c))
+        throw new Error(`lcsc:${code}: an LCSC part number is C and digits, such as C965555`);
+    const api = `https://easyeda.com/api/products/${c}/components`;
+    const r = await fetcher(api, { headers: { accept: 'application/json' } });
+    const j = r.ok ? await r.json().catch(() => null) : null;
+    if (!j?.success || !j.result)
+        throw new Error(`${c}: not in EasyEDA's library (${api}: ${j?.message ?? `HTTP ${r.status}`})`);
+    let ds = j.result.packageDetail?.dataStr;
+    if (typeof ds === 'string') {
+        try {
+            ds = JSON.parse(ds);
+        }
+        catch {
+            ds = null;
+        }
+    }
+    let model = null;
+    for (const sh of ds?.shape ?? []) {
+        if (typeof sh !== 'string' || !sh.startsWith('SVGNODE~'))
+            continue;
+        try {
+            const a = JSON.parse(sh.slice(8)).attrs;
+            if (a?.c_etype === 'outline3D' && /^[0-9a-f]{32}$/.test(a.uuid)) {
+                model = { uuid: a.uuid, title: String(a.title ?? c) };
+                break;
+            }
+        }
+        catch { /* not a node */ }
+    }
+    const pkg = String(j.result.packageDetail?.title ?? '');
+    if (!model)
+        throw new Error(`${c}: EasyEDA's footprint ${pkg || 'for it'} has no 3D model`);
+    const url = EASYEDA_MODELS + model.uuid;
+    const m = await fetcher(url);
+    if (!m.ok)
+        throw new Error(`${c}: ${url}: HTTP ${m.status}`);
+    return { data: new Uint8Array(await m.arrayBuffer()), name: `${model.title}.step`, url, note: `LCSC ${c} ${j.result.title ?? ''}, EasyEDA library model ${model.title}`.replace(/\s+/g, ' ') };
+}
+/** Download a source into the project's cache, the file written whole or not at all, and note its licence. */
+export async function download(root, source) {
+    const dest = fetchedPath(root, source);
+    let data, from;
+    if (/^lcsc:/i.test(source)) {
+        const m = await lcscModel(source.slice(5).trim());
+        data = m.data;
+        from = `${m.note}, ${m.url}`;
+    }
+    else {
+        const url = sourceUrl(source);
+        const r = await fetch(url, { redirect: 'follow' });
+        if (!r.ok)
+            throw new Error(`${url}: HTTP ${r.status}`);
+        data = new Uint8Array(await r.arrayBuffer());
+        if (!/ISO-10303-21/.test(new TextDecoder().decode(data.subarray(0, 64))))
+            throw new Error(`${url}: not a STEP file`);
+        from = url;
+    }
+    mkdirSync(dirname(dest), { recursive: true });
+    const tmp = `${dest}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
+    try {
+        writeFileSync(tmp, data);
+        renameSync(tmp, dest);
+    }
+    finally {
+        rmSync(tmp, { force: true });
+    }
+    const dir = fetchedDir(root);
+    noteSource(dir, relative(dir, dest).split(sep).join('/'), `${from}; ${licenceOf(source)}`);
+    return dest;
+}
+/** A `kicad:` source from an installed KiCad library, else null. */
+function installed(source) {
+    if (!/^kicad:/i.test(source))
+        return null;
+    const file = kicadModel(`\${KICAD9_3DMODEL_DIR}/${kicadPath(source)}`);
+    return !file.startsWith('${') && existsSync(file) ? file : null;
+}
+const CHILD = fileURLToPath(new URL('./fetch-model-child.js', import.meta.url));
+// sources that did not download in this process, and whether the network is down, so a compile tries each once
+const STATE = Symbol.for('pcbjs.cli.fetchModel');
+const envOffline = () => (process.env.PCBJS_OFFLINE ? 'PCBJS_OFFLINE is set' : null);
+const state = () => (globalThis[STATE] ??= { failed: new Map(), offline: envOffline(), told: new Set() });
+/** Forget the failures of this process, for `model fetch`. */
+export function retryFetches() { const s = state(); s.failed.clear(); s.told.clear(); s.offline = envOffline(); }
+/** The resolver the compile calls for each fetched model: the installed KiCad library, the cache, or a download in a child process. */
+export function remoteResolver(root) {
+    return source => {
+        const local = installed(source);
+        if (local)
+            return local;
+        const dest = fetchedPath(root, source);
+        if (existsSync(dest))
+            return dest;
+        const s = state();
+        if (s.failed.has(source))
+            return null;
+        let why = s.offline;
+        if (!why) {
+            const r = spawnSync(process.execPath, [CHILD, root, source], { encoding: 'utf8', timeout: 60_000 });
+            if (existsSync(dest))
+                return dest;
+            why = (r.stderr || r.error?.message || 'the download timed out').trim().split('\n')[0];
+            if (r.status === 2 || r.error)
+                s.offline = why;
+        }
+        s.failed.set(source, why);
+        return null;
+    };
+}
+/** One line for the parts of a board whose models did not download, once per process for the same parts. */
+export function fetchNotice(board, waiting) {
+    if (!waiting.length)
+        return null;
+    const s = state(), refs = waiting.map(w => w.ref);
+    const key = `${board}:${refs.join(',')}`;
+    if (s.told.has(key))
+        return null;
+    s.told.add(key);
+    const why = [...new Set(waiting.map(w => s.failed.get(w.source)).filter(Boolean))].join('; ') || 'not fetched';
+    const list = refs.length > 6 ? `${refs.slice(0, 6).join(', ')} and ${refs.length - 6} more` : refs.join(', ');
+    return `pcbjs: ${board}: ${list} ${refs.length === 1 ? 'shows a dashed outline' : 'show dashed outlines'}, the model did not download (${why}); run pcbjs model fetch`;
+}
+/** Let the next compile of this project resolve and fetch its models; the compile is synchronous, so each sets its own root. */
+export function installModelFetch(root) {
+    ;
+    globalThis[REMOTE_MODEL] = remoteResolver(root);
+}

package/dist/host-client.d.ts

@@ -0,0 +1,60 @@
+/** Additive, the same number as @pcbjs/lsp's PROTOCOL. */
+export declare const IDE_PROTOCOL = 2;
+/** Bumped only by a change an older peer cannot survive. */
+export declare const IDE_MAJOR = 1;
+export interface HostHello {
+    name: string;
+    version: string;
+    protocol: number;
+    major: number;
+    capabilities: string[] | null;
+}
+export interface HostCursor {
+    file: string;
+    line: number;
+    col: number;
+}
+export interface HostFocus {
+    file: string;
+}
+export interface HostClientOptions {
+    /** `ws://127.0.0.1:<port>/<token>`, already checked with parseIdeUrl */
+    url: string;
+    onHello?(hello: HostHello): void;
+    onCursor?(cursor: HostCursor): void;
+    onFocus?(focus: HostFocus): void;
+    onClose?(close: HostFocus): void;
+    onBye?(): void;
+    onRpc?(msg: unknown): void;
+    /** once per connection and once per run of failed attempts */
+    onStatus?(status: 'connected' | 'disconnected' | 'unreachable', detail?: string): void;
+    /** ms, doubled per failed attempt up to maxDelay */
+    minDelay?: number;
+    maxDelay?: number;
+}
+export interface HostClient {
+    /** False while disconnected; STICKY events are sent again on every reconnect. */
+    send(event: string, data: unknown): boolean;
+    sendRpc(msg: unknown): boolean;
+    connected(): boolean;
+    hello(): HostHello | null;
+    close(): void;
+}
+export declare const STICKY: readonly ["pcbjs:ide:ready", "pcbjs:ide:scopes", "pcbjs:ide:scope", "pcbjs:ide:boards"];
+/** Throws a message for the CLI unless ws or wss and loopback, or allowRemote. */
+export declare function parseIdeUrl(url: string, allowRemote?: boolean): URL;
+/** Without path and query, so the token never reaches the terminal. */
+export declare const redactUrl: (url: string) => string;
+/** What `ready` offers: the events it takes, and `lsp` when @pcbjs/lsp resolves. */
+export declare function serverCapabilities(): string[];
+export declare const readyProtocol: () => {
+    protocol: number;
+    major: number;
+    capabilities: string[];
+};
+/** A hello without `protocol` comes from a protocol 1 editor. */
+export declare function parseHello(d: any): HostHello;
+/** Null unless the editor's protocol major is older than this server's. */
+export declare function helloWarning(h: HostHello): string | null;
+/** Keeps dialling with a backoff until close(). */
+export declare function connectHost(opts: HostClientOptions): HostClient;