@markii/pack 0.16.0 → 0.17.0-next.1

package/dist/archive.d.ts

@@ -41,6 +41,8 @@ export interface PackArchiveContents {
     readonly scriptBytes: Uint8Array;
     /** The prebuilt stylesheet's bytes (`webview.css`), present only when the pack ships one. */
     readonly stylesheetBytes?: Uint8Array;
+    /** The prebuilt terminal registration module (`terminal.js`), present only when the pack ships terminal views. Hosts that run no terminal engine ignore it. */
+    readonly terminalScriptBytes?: Uint8Array;
     /** Shared Lua modules under `scripts/`, keyed by their path relative to that folder (e.g. `"http.lua"` for `scripts/http.lua`). Empty when the pack ships none. */
     readonly scriptModules: Readonly<Record<string, Uint8Array>>;
     /**

package/dist/archive.js

@@ -1,7 +1,7 @@
 /**
  * `.mkp` pack archives (docs/packs.md, issue #16): a zip of a pack's
  * PREBUILT form, files at the zip root — `pack.json`, `webview.js`,
- * `webview.css` when the pack has styles, `scripts/` when the pack ships
+ * `webview.css` when the pack has styles, `terminal.js` when it ships terminal views, `scripts/` when the pack ships
  * shared Lua. This is the reader half: given the raw bytes of a `.mkp`
  * file, validate it and expose its contents for read-only loading.
  *
@@ -37,6 +37,8 @@ import { parsePackManifest } from './manifest.js';
 const MANIFEST_ENTRY = 'pack.json';
 const SCRIPT_ENTRY = 'webview.js';
 const STYLESHEET_ENTRY = 'webview.css';
+/** The optional terminal registration module (docs/packs.md). A pack with no terminal views has none. */
+const TERMINAL_ENTRY = 'terminal.js';
 const SCRIPTS_DIR_PREFIX = 'scripts/';
 /** macOS's zip metadata folder — never a real pack file, and never counted toward "is this archive a single wrapped folder" detection below (batch 7 #61). */
 const MACOSX_PREFIX = '__MACOSX/';
@@ -198,12 +200,17 @@ export async function openPackArchive(bytes, options = {}) {
     if (paths.includes(STYLESHEET_ENTRY)) {
         stylesheetBytes = await storage.read(STYLESHEET_ENTRY);
     }
+    let terminalScriptBytes;
+    if (paths.includes(TERMINAL_ENTRY)) {
+        terminalScriptBytes = await storage.read(TERMINAL_ENTRY);
+    }
     const scriptModules = Object.create(null);
     const ignoredEntries = [];
     for (const path of paths) {
         if (path === MANIFEST_ENTRY ||
             path === SCRIPT_ENTRY ||
-            path === STYLESHEET_ENTRY) {
+            path === STYLESHEET_ENTRY ||
+            path === TERMINAL_ENTRY) {
             continue;
         }
         if (isScriptModulePath(path)) {
@@ -222,6 +229,7 @@ export async function openPackArchive(bytes, options = {}) {
             manifestWarnings: parsed.warnings,
             scriptBytes,
             ...(stylesheetBytes !== undefined ? { stylesheetBytes } : {}),
+            ...(terminalScriptBytes !== undefined ? { terminalScriptBytes } : {}),
             scriptModules,
             ignoredEntries,
         },

package/dist/components.d.ts

@@ -71,7 +71,14 @@ export interface PackComponentAttribute {
  * hover documentation.
  */
 export interface PackComponentDefinition {
-    source: string;
+    /** The source for the pack's top-level `engine`. Mutually exclusive with `sources`. */
+    source?: string;
+    /**
+     * Engine id -> pack-relative source path, for a component that ships
+     * more than one implementation (for example `react` and `ansi`).
+     * Mutually exclusive with `source`.
+     */
+    sources?: Readonly<Record<string, string>>;
     description?: string;
     kind?: PackComponentKind;
     /**
@@ -93,7 +100,13 @@ export type PackComponentEntry = string | PackComponentDefinition;
  * the manifest declared them (the string shorthand never has any of them).
  */
 export interface ResolvedPackComponent {
-    readonly source: string;
+    /**
+     * Engine id -> pack-relative source path, normalized from all three
+     * declared forms (string shorthand and `source` are keyed under the
+     * manifest's `engine`). Read it through `componentSourceForEngine`.
+     * Never empty. A null-prototype object.
+     */
+    readonly sources: Readonly<Record<string, string>>;
     readonly description?: string;
     readonly kind?: PackComponentKind;
     readonly attributes?: readonly PackComponentAttribute[];
@@ -102,6 +115,38 @@ export interface ResolvedPackComponent {
 export interface PackComponentListing extends ResolvedPackComponent {
     readonly localName: string;
 }
+/** A listing narrowed to one engine: `source` is that engine's source path. */
+export interface EnginePackComponentListing extends PackComponentListing {
+    readonly source: string;
+}
+/**
+ * The pack-relative source this component has for `engine`, or `undefined`
+ * when it ships none. The one answer to "does this component run here".
+ */
+export declare function componentSourceForEngine(component: Pick<ResolvedPackComponent, 'sources'>, engine: string): string | undefined;
+/**
+ * Whether a host for `engine` should install the pack: true when the pack
+ * declares no components (Lua-only) or at least one component has a source
+ * for `engine`. A pack with components but none for this engine is not
+ * installable here and a host reports it as dropped.
+ */
+export declare function packSupportsEngine(manifest: Pick<PackManifest, 'components' | 'engine'>, engine: string): boolean;
+/**
+ * The pack's components that have a source for `engine`, in declaration
+ * order, each carrying that engine's `source`. Components without one are
+ * absent (they fall back to the unknown-component box in that engine).
+ */
+export declare function packComponentsForEngine(manifest: Pick<PackManifest, 'components' | 'engine'>, engine: string): EnginePackComponentListing[];
+/**
+ * Every engine id any component of the pack ships a source for, sorted,
+ * comma-joined for a "dropped pack" report. Falls back to the manifest's
+ * top-level `engine` when the pack declares no components.
+ */
+export declare function packDeclaredEngines(manifest: Pick<PackManifest, 'components' | 'engine'>): string;
+/** Engine ids are lowercase words: a leading letter, then lowercase letters, digits and hyphens. */
+export declare const PACK_ENGINE_ID_PATTERN: RegExp;
+/** Whether `id` is a usable engine id (a `sources` key). */
+export declare function isPackEngineId(id: unknown): id is string;
 /**
  * Normalizes a single `components` entry, string or object form, into the
  * common `ResolvedPackComponent` shape. This is THE accessor for reading
@@ -116,8 +161,11 @@ export interface PackComponentListing extends ResolvedPackComponent {
  * a value. This matters because a consumer may call this directly on
  * attacker-controlled JSON that never went through `parsePackManifest` at
  * all (for example a pack loaded from an untrusted bundle).
+ *
+ * `defaultEngine` is the manifest's top-level `engine`: the engine the
+ * string shorthand and an object entry's `source` are written for.
  */
-export declare function resolvePackComponent(entry: unknown): ResolvedPackComponent | undefined;
+export declare function resolvePackComponent(entry: unknown, defaultEngine: string): ResolvedPackComponent | undefined;
 /**
  * THE iterator every consumer uses instead of walking `manifest.components`
  * directly: `Object.hasOwn`-guarded, in declaration key order, skipping any
@@ -131,4 +179,4 @@ export declare function resolvePackComponent(entry: unknown): ResolvedPackCompon
  * object, or an array: all of those return `[]` rather than throwing, so a
  * caller never needs to guard the call site itself.
  */
-export declare function packComponents(manifest: Pick<PackManifest, 'components'>): PackComponentListing[];
+export declare function packComponents(manifest: Pick<PackManifest, 'components' | 'engine'>): PackComponentListing[];

package/dist/components.js

@@ -29,6 +29,92 @@ export const PACK_ATTRIBUTE_NAME_PATTERN = /^[a-z][a-z0-9-]*$/;
 export function isPackAttributeName(name) {
     return typeof name === 'string' && PACK_ATTRIBUTE_NAME_PATTERN.test(name);
 }
+/**
+ * The pack-relative source this component has for `engine`, or `undefined`
+ * when it ships none. The one answer to "does this component run here".
+ */
+export function componentSourceForEngine(component, engine) {
+    return Object.hasOwn(component.sources, engine)
+        ? component.sources[engine]
+        : undefined;
+}
+/**
+ * Whether a host for `engine` should install the pack: true when the pack
+ * declares no components (Lua-only) or at least one component has a source
+ * for `engine`. A pack with components but none for this engine is not
+ * installable here and a host reports it as dropped.
+ */
+export function packSupportsEngine(manifest, engine) {
+    const all = packComponents(manifest);
+    if (all.length === 0)
+        return true;
+    return all.some((c) => componentSourceForEngine(c, engine) !== undefined);
+}
+/**
+ * The pack's components that have a source for `engine`, in declaration
+ * order, each carrying that engine's `source`. Components without one are
+ * absent (they fall back to the unknown-component box in that engine).
+ */
+export function packComponentsForEngine(manifest, engine) {
+    const result = [];
+    for (const listing of packComponents(manifest)) {
+        const source = componentSourceForEngine(listing, engine);
+        if (source !== undefined)
+            result.push({ ...listing, source });
+    }
+    return result;
+}
+/**
+ * Every engine id any component of the pack ships a source for, sorted,
+ * comma-joined for a "dropped pack" report. Falls back to the manifest's
+ * top-level `engine` when the pack declares no components.
+ */
+export function packDeclaredEngines(manifest) {
+    const ids = new Set();
+    for (const listing of packComponents(manifest)) {
+        for (const id of Object.keys(listing.sources))
+            ids.add(id);
+    }
+    if (ids.size === 0)
+        ids.add(manifest.engine);
+    return [...ids].sort().join(', ');
+}
+/** Engine ids are lowercase words: a leading letter, then lowercase letters, digits and hyphens. */
+export const PACK_ENGINE_ID_PATTERN = /^[a-z][a-z0-9-]*$/;
+/** Whether `id` is a usable engine id (a `sources` key). */
+export function isPackEngineId(id) {
+    return typeof id === 'string' && PACK_ENGINE_ID_PATTERN.test(id);
+}
+function nullProto(entries) {
+    const out = Object.create(null);
+    for (const [k, v] of entries)
+        out[k] = v;
+    return out;
+}
+/** Reads the engine-to-source map of an object entry, leniently: bad pairs are dropped. */
+function resolveSources(entry, defaultEngine) {
+    const source = ownProperty(entry, 'source');
+    const sources = ownProperty(entry, 'sources');
+    if (typeof source === 'string' && source.length > 0) {
+        if (sources !== undefined)
+            return undefined;
+        return nullProto([[defaultEngine, source]]);
+    }
+    if (sources === null ||
+        typeof sources !== 'object' ||
+        Array.isArray(sources)) {
+        return undefined;
+    }
+    const pairs = [];
+    for (const key of Object.keys(sources)) {
+        if (!Object.hasOwn(sources, key) || !isPackEngineId(key))
+            continue;
+        const value = sources[key];
+        if (typeof value === 'string' && value.length > 0)
+            pairs.push([key, value]);
+    }
+    return pairs.length > 0 ? nullProto(pairs) : undefined;
+}
 /**
  * Reads one own property off an already-narrowed object, or `undefined`
  * when it is absent. `Object.hasOwn` only, matching this package's rule
@@ -112,20 +198,24 @@ function resolveAttributes(raw) {
  * a value. This matters because a consumer may call this directly on
  * attacker-controlled JSON that never went through `parsePackManifest` at
  * all (for example a pack loaded from an untrusted bundle).
+ *
+ * `defaultEngine` is the manifest's top-level `engine`: the engine the
+ * string shorthand and an object entry's `source` are written for.
  */
-export function resolvePackComponent(entry) {
+export function resolvePackComponent(entry, defaultEngine) {
     if (typeof entry === 'string') {
-        return entry.length > 0 ? { source: entry } : undefined;
+        return entry.length > 0
+            ? { sources: nullProto([[defaultEngine, entry]]) }
+            : undefined;
     }
     if (entry === null || typeof entry !== 'object' || Array.isArray(entry)) {
         return undefined;
     }
-    const source = ownProperty(entry, 'source');
-    if (typeof source !== 'string' || source.length === 0) {
+    const sources = resolveSources(entry, defaultEngine);
+    if (sources === undefined)
         return undefined;
-    }
     const result = {
-        source,
+        sources,
     };
     const description = ownProperty(entry, 'description');
     if (typeof description === 'string' && description.length > 0) {
@@ -156,6 +246,7 @@ export function resolvePackComponent(entry) {
  */
 export function packComponents(manifest) {
     const components = manifest?.components;
+    const engine = manifest?.engine;
     if (components === null ||
         typeof components !== 'object' ||
         Array.isArray(components)) {
@@ -165,7 +256,7 @@ export function packComponents(manifest) {
     for (const localName of Object.keys(components)) {
         if (!Object.hasOwn(components, localName))
             continue;
-        const resolved = resolvePackComponent(components[localName]);
+        const resolved = resolvePackComponent(components[localName], typeof engine === 'string' ? engine : '');
         if (resolved === undefined)
             continue;
         listings.push({ localName, ...resolved });

package/dist/index.d.ts

@@ -2,8 +2,8 @@ export type { PackManifest, PackManifestParseResult } from './manifest.js';
 export { parsePackManifest } from './manifest.js';
 export type { OpenPackArchiveOptions, OpenPackArchiveResult, PackArchiveContents, PackArchiveError, } from './archive.js';
 export { openPackArchive, packArchiveFileName } from './archive.js';
-export type { PackComponentAttribute, PackComponentDefinition, PackComponentEntry, PackComponentKind, PackComponentListing, ResolvedPackComponent, } from './components.js';
-export { PACK_ATTRIBUTE_NAME_PATTERN, PACK_COMPONENT_KINDS, isPackAttributeName, packComponents, resolvePackComponent, } from './components.js';
+export type { PackComponentAttribute, PackComponentDefinition, PackComponentEntry, PackComponentKind, EnginePackComponentListing, PackComponentListing, ResolvedPackComponent, } from './components.js';
+export { PACK_ATTRIBUTE_NAME_PATTERN, PACK_COMPONENT_KINDS, PACK_ENGINE_ID_PATTERN, componentSourceForEngine, isPackAttributeName, isPackEngineId, packComponents, packComponentsForEngine, packDeclaredEngines, packSupportsEngine, resolvePackComponent, } from './components.js';
 export type { ComposeDirectiveNameResult, NamespaceCollision, NamespaceValidationResult, } from './namespace.js';
 export { RESERVED_NAMESPACE_SEGMENTS, composeDirectiveName, detectNamespaceCollisions, validateLocalComponentName, validatePackName, } from './namespace.js';
 export type { UsesResolution } from './uses.js';

package/dist/index.js

@@ -7,6 +7,6 @@
 // out, touching no real filesystem itself (a host does that).
 export { parsePackManifest } from './manifest.js';
 export { openPackArchive, packArchiveFileName } from './archive.js';
-export { PACK_ATTRIBUTE_NAME_PATTERN, PACK_COMPONENT_KINDS, isPackAttributeName, packComponents, resolvePackComponent, } from './components.js';
+export { PACK_ATTRIBUTE_NAME_PATTERN, PACK_COMPONENT_KINDS, PACK_ENGINE_ID_PATTERN, componentSourceForEngine, isPackAttributeName, isPackEngineId, packComponents, packComponentsForEngine, packDeclaredEngines, packSupportsEngine, resolvePackComponent, } from './components.js';
 export { RESERVED_NAMESPACE_SEGMENTS, composeDirectiveName, detectNamespaceCollisions, validateLocalComponentName, validatePackName, } from './namespace.js';
 export { isValidPackNameShape, resolveUses } from './uses.js';

package/dist/manifest.js

@@ -1,5 +1,5 @@
 import { validateLocalComponentName, validatePackName } from './namespace.js';
-import { PACK_ATTRIBUTE_NAME_PATTERN, PACK_COMPONENT_KINDS, isPackAttributeName, } from './components.js';
+import { PACK_ATTRIBUTE_NAME_PATTERN, PACK_COMPONENT_KINDS, PACK_ENGINE_ID_PATTERN, isPackAttributeName, isPackEngineId, } from './components.js';
 const KNOWN_TOP_LEVEL_KEYS = new Set([
     'name',
     'engine',
@@ -16,6 +16,7 @@ const SEMVER_PATTERN = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
 // an unrecognized key here is a forward-compatible warning, not an error.
 const KNOWN_COMPONENT_KEYS = new Set([
     'source',
+    'sources',
     'description',
     'kind',
     'attributes',
@@ -266,11 +267,57 @@ export function parsePackManifest(json) {
             // the raw parsed one — the same discipline as the string-form branch
             // and as the top-level Object.hasOwn guarding throughout this file.
             let entryValid = true;
-            const source = Object.hasOwn(value, 'source') ? value.source : undefined;
-            if (typeof source !== 'string' || source.length === 0) {
-                errors.push(`"components.${key}.source" must be a non-empty string (a pack-relative source path)`);
+            const hasSource = Object.hasOwn(value, 'source');
+            const hasSources = Object.hasOwn(value, 'sources');
+            const source = hasSource ? value.source : undefined;
+            let sourcesMap;
+            if (hasSource && hasSources) {
+                errors.push(`"components.${key}" must carry "source" or "sources", not both`);
                 entryValid = false;
             }
+            else if (!hasSource && !hasSources) {
+                errors.push(`"components.${key}.source" is required (a pack-relative source path), or give a "sources" map instead`);
+                entryValid = false;
+            }
+            else if (hasSource) {
+                if (typeof source !== 'string' || source.length === 0) {
+                    errors.push(`"components.${key}.source" must be a non-empty string (a pack-relative source path)`);
+                    entryValid = false;
+                }
+            }
+            else {
+                const rawSources = value.sources;
+                if (!isPlainObject(rawSources)) {
+                    errors.push(`"components.${key}.sources" must be an object mapping engine ids to pack-relative source paths`);
+                    entryValid = false;
+                }
+                else {
+                    const parsedSources = Object.create(null);
+                    let count = 0;
+                    for (const engineId of Object.keys(rawSources)) {
+                        if (!Object.hasOwn(rawSources, engineId))
+                            continue;
+                        count += 1;
+                        const path = rawSources[engineId];
+                        if (!isPackEngineId(engineId)) {
+                            errors.push(`"components.${key}.sources" key "${engineId}" must be a lowercase engine id matching ${PACK_ENGINE_ID_PATTERN.source}`);
+                            entryValid = false;
+                        }
+                        else if (typeof path !== 'string' || path.length === 0) {
+                            errors.push(`"components.${key}.sources.${engineId}" must be a non-empty string (a pack-relative source path)`);
+                            entryValid = false;
+                        }
+                        else {
+                            parsedSources[engineId] = path;
+                        }
+                    }
+                    if (count === 0) {
+                        errors.push(`"components.${key}.sources" must name at least one engine`);
+                        entryValid = false;
+                    }
+                    sourcesMap = parsedSources;
+                }
+            }
             let description;
             if (Object.hasOwn(value, 'description')) {
                 const rawDescription = value.description;
@@ -325,7 +372,7 @@ export function parsePackManifest(json) {
             // field was present — only the string shorthand collapses to a bare
             // string. This preserves the author's declared form rather than
             // silently normalizing `{ "source": "./x.tsx" }` into `"./x.tsx"`.
-            const sanitized = { source: source };
+            const sanitized = hasSource ? { source: source } : { sources: sourcesMap };
             if (description !== undefined)
                 sanitized.description = description;
             if (kind !== undefined)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@markii/pack",
-  "version": "0.16.0",
+  "version": "0.17.0-next.1",
   "description": "Component pack contract for Markii (docs/packs.md): the pack.json manifest shape, namespace and engine rules, hand-rolled validation, and the .mkp prebuilt-archive reader. No React, no parsing.",
   "keywords": [
     "markdown",
@@ -42,6 +42,6 @@
     "lint": "eslint ."
   },
   "dependencies": {
-    "@markii/bundle": "^0.16.0"
+    "@markii/bundle": "^0.17.0-next.1"
   }
 }