@12ui/design 0.2.55 → 0.2.57

package/dist/improve-kit-assets.js

@@ -0,0 +1,333 @@
+import { readFile, readdir, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { flattenLayerDoc, isRecord } from './improve-layerdoc-diff.js';
+/**
+ * What the kit's extracted files ARE, named once.
+ *
+ * Two overnight lanes threw the design away because nothing in the kit said
+ * that `cutout-1-….png` was the hero artwork and `clean-0-….png` was the same
+ * backdrop with that artwork removed. One of them hand-drew the ribbon in CSS
+ * and crushed the plate under a 64% scrim. The role wording below is the fixed
+ * answer, and every renderer — README, plan, stall report — reads it from here
+ * so no two surfaces can describe the same file differently.
+ */
+/** A layer covering at least this share of the canvas is the page's imagery, not a detail. */
+export const IMPROVE_HERO_COVERAGE = 0.25;
+/** The most a readability scrim may dim a plate before it is destroying the design. */
+export const IMPROVE_SCRIM_MAX_OPACITY_PCT = 35;
+/**
+ * The disposition of every clean plate that is not the page's backdrop.
+ *
+ * A conversion can emit several: `clean-0` is the backdrop with the artwork
+ * removed, `clean-1` is that same backdrop with a further layer removed too.
+ * Both used to read `ship`, with no layer and no placement, and a lane shipped
+ * `clean-1` — a page whose backdrop had erased the layer nothing else replaced.
+ */
+export const IMPROVE_ALTERNATE_BACKDROP = 'alternate backdrop (only if that layer is omitted)';
+export const IMPROVE_ASSET_ROLE_COPY = {
+    'clean-plate': {
+        label: 'clean plate',
+        instruction: 'the backdrop with the foreground artwork removed.'
+            + ' Use it as the background layer, at full strength.',
+    },
+    cutout: {
+        label: 'cutout',
+        instruction: 'the foreground artwork as an alpha PNG. This is the imagery.'
+            + ' Copy it into the repo and place it at its bounds; never redraw it in CSS.',
+    },
+    'upscaled-plate': {
+        label: 'upscaled plate',
+        instruction: 'a higher-resolution copy of a plate for crisp rendering;'
+            + ' pick one resolution, do not ship both.',
+    },
+    'upscaled-region': {
+        label: 'upscaled region',
+        instruction: 'a higher-resolution copy of a region for crisp rendering;'
+            + ' pick one resolution, do not ship both.',
+    },
+    'source-crop': {
+        label: 'source crop',
+        instruction: 'the layer cropped straight out of the source image.'
+            + ' Prefer that layer\'s cutout when one exists.',
+    },
+    'prepared-source': {
+        label: 'prepared source',
+        instruction: 'the normalized image the conversion read; the same picture as `winner.png`.',
+    },
+    design: {
+        label: 'winner.png',
+        instruction: 'the whole design; the reference for every visual decision.',
+    },
+    other: {
+        label: 'extracted artifact',
+        instruction: 'an extracted artifact the conversion produced for a layer.',
+    },
+};
+/** Artifact keys a LayerDoc leaf may carry, best carrier first. */
+const CARRIER_PREFERENCE = ['cutout', 'plate', 'crop', 'region2x', 'plate2x'];
+const ROLE_BY_MANIFEST = {
+    'cleaned-plate': 'clean-plate',
+    'layer-cutout': 'cutout',
+    'layer-crop': 'source-crop',
+    'upscaled-plate': 'upscaled-plate',
+    'upscaled-region': 'upscaled-region',
+    source: 'prepared-source',
+};
+const ROLE_BY_ID_PREFIX = [
+    ['upscaled-plate-', 'upscaled-plate'],
+    ['upscaled-region-', 'upscaled-region'],
+    ['clean-', 'clean-plate'],
+    ['cutout-', 'cutout'],
+    ['crop-', 'source-crop'],
+];
+/**
+ * What a file is for before the LayerDoc's layers are known. A carrier that no
+ * layer claims is still a carrier: only the resolution aids and the two
+ * whole-design references are never copied in.
+ */
+const dispositionByRole = (role) => {
+    if (role === 'design' || role === 'prepared-source')
+        return 'reference only';
+    if (role === 'upscaled-plate' || role === 'upscaled-region')
+        return 'alternate resolution';
+    return 'ship';
+};
+const assetRole = (id, manifestRole) => {
+    if (typeof manifestRole === 'string' && ROLE_BY_MANIFEST[manifestRole]) {
+        return ROLE_BY_MANIFEST[manifestRole];
+    }
+    if (id === 'source')
+        return 'prepared-source';
+    return ROLE_BY_ID_PREFIX.find(([prefix]) => id.startsWith(prefix))?.[1] ?? 'other';
+};
+const boxOfLeaf = (leaf) => (Array.isArray(leaf.box) && leaf.box.length === 4
+    && leaf.box.every((value) => typeof value === 'number' && Number.isFinite(value))
+    ? leaf.box
+    : undefined);
+const layerName = (leaf) => {
+    const named = leaf.name;
+    const content = typeof leaf.content === 'string' && leaf.content.trim() ? leaf.content.trim() : undefined;
+    if (content)
+        return content;
+    if (typeof named === 'string' && named.trim())
+        return named.trim();
+    return leaf.kind ?? 'layer';
+};
+const artifactIdsOf = (leaf) => {
+    const artifacts = leaf.artifacts;
+    if (!isRecord(artifacts))
+        return [];
+    return Object.entries(artifacts).flatMap(([key, value]) => (isRecord(value) && typeof value.artifactId === 'string'
+        ? [{ key, id: value.artifactId }]
+        : [])).sort((left, right) => {
+        const rank = (key) => {
+            const index = CARRIER_PREFERENCE.indexOf(key);
+            return index < 0 ? CARRIER_PREFERENCE.length : index;
+        };
+        return rank(left.key) - rank(right.key);
+    });
+};
+export const boundsPct = (box, canvas) => ({
+    x: (box[0] / canvas.width) * 100,
+    y: (box[1] / canvas.height) * 100,
+    width: (box[2] / canvas.width) * 100,
+    height: (box[3] / canvas.height) * 100,
+});
+/**
+ * Which frame the percentages above belong to.
+ *
+ * A lane read the plan's bounds as pixels of `winner.png` and placed every
+ * layer short: the design is its own size (1536x1024 in that run) while the
+ * page being rebuilt is the capture frame (1440x900). A percentage is the same
+ * number in both frames, so the fix is one line naming the frame — rendered
+ * from here so the README and the plan cannot word it differently.
+ */
+export const improveFrameMappingLine = (args) => {
+    const size = (value) => (value ? ` (${value.width}\u00d7${value.height})` : '');
+    return `Bounds are % of the capture frame${size(args.frame)};`
+        + ` \`winner.png\` is the design at its own size${size(args.design)};`
+        + ' place by percentage, not by pixel.';
+};
+export const formatImproveBounds = (bounds) => (`x ${bounds.x.toFixed(1)}%, y ${bounds.y.toFixed(1)}%,`
+    + ` ${bounds.width.toFixed(1)}% × ${bounds.height.toFixed(1)}% of the canvas`);
+const canvasOf = (document) => {
+    if (!isRecord(document) || !isRecord(document.canvas))
+        return undefined;
+    const { width, height } = document.canvas;
+    return typeof width === 'number' && typeof height === 'number' && width > 0 && height > 0
+        ? { width, height }
+        : undefined;
+};
+const readJson = async (file) => {
+    try {
+        return JSON.parse(await readFile(file, 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+};
+const fileExists = async (file) => Boolean(await stat(file).then(() => true).catch(() => false));
+/**
+ * Resolve one manifest artifact to a file that is actually in this kit.
+ *
+ * `localPath` is absolute and recorded where the conversion ran, so a moved or
+ * copied kit resolves through the basename first. A directory scan closes the
+ * remaining gap: freshdesk's kit holds two files for `clean-0` from two
+ * attempts, and only the manifest says which one the LayerDoc means.
+ */
+const resolveAssetFile = async (args) => {
+    const declared = typeof args.localPath === 'string' && args.localPath ? args.localPath : undefined;
+    const basename = declared ? path.basename(declared) : undefined;
+    if (basename) {
+        const local = path.join(args.assetsDir, basename);
+        if (await fileExists(local))
+            return { absolute: local, present: true };
+    }
+    const scanned = args.names.find((name) => name.startsWith(`${args.id}-`) || name === args.id);
+    if (scanned)
+        return { absolute: path.join(args.assetsDir, scanned), present: true };
+    if (declared && await fileExists(declared))
+        return { absolute: declared, present: true };
+    return { absolute: path.join(args.assetsDir, basename ?? args.id), present: false };
+};
+/** The number a `clean-N`, `cutout-N`, or `crop-N` id carries. */
+const artifactNumber = (id) => {
+    const match = /-(\d+)$/u.exec(id);
+    return match ? Number(match[1]) : undefined;
+};
+/**
+ * Exactly one clean plate is the page's backdrop; the rest are alternates.
+ *
+ * The document settles which: the plate a background layer references, or —
+ * when no layer references one at all — the plate whose number pairs with the
+ * largest decoration, because that is the layer it erased. Everything else is
+ * the same backdrop minus a further layer, so it is only the background if that
+ * layer is left out. Marking them all `ship` is what let a lane ship `clean-1`.
+ */
+const classifyCleanPlates = (args) => {
+    const plates = args.assets.filter((asset) => asset.role === 'clean-plate');
+    if (plates.length < 2)
+        return;
+    const layerByNumber = new Map();
+    for (const layer of args.rasterLayers) {
+        for (const asset of [layer.asset, ...layer.alternates]) {
+            const number = asset ? artifactNumber(asset.id) : undefined;
+            if (number !== undefined && !layerByNumber.has(number))
+                layerByNumber.set(number, layer);
+        }
+    }
+    const pairedWith = (plate) => {
+        const number = artifactNumber(plate.id);
+        return number === undefined ? undefined : layerByNumber.get(number);
+    };
+    const carried = new Set(args.rasterLayers.flatMap((layer) => (layer.asset ? [layer.asset.id] : [])));
+    const base = plates.find((plate) => plate.layer?.kind === 'background' && carried.has(plate.id))
+        ?? [...plates].sort((left, right) => ((pairedWith(right)?.coverage ?? -1) - (pairedWith(left)?.coverage ?? -1)
+            || left.id.localeCompare(right.id)))[0];
+    for (const plate of plates) {
+        if (plate.id === base?.id) {
+            plate.ship = 'ship';
+            continue;
+        }
+        const paired = pairedWith(plate);
+        plate.ship = IMPROVE_ALTERNATE_BACKDROP;
+        plate.instruction = 'the same backdrop with '
+            + (paired ? `the ${paired.kind} \`${paired.name}\`` : 'a further layer')
+            + ' removed as well. It is the background only if you omit that layer;'
+            + ' otherwise ship the base clean plate.';
+    }
+};
+/** A plate the README calls an alternate must never be listed as one to carry. */
+export const isImproveAlternateBackdrop = (asset) => (asset?.ship === IMPROVE_ALTERNATE_BACKDROP);
+/** The raster layers a plan tells a reader to copy in: alternates are not among them. */
+export const improveCarriedRasterLayers = (layers) => layers.filter((layer) => !isImproveAlternateBackdrop(layer.asset));
+/**
+ * Read the kit's LayerDoc and asset manifest into one table the README, the
+ * plan, and the stall report all render from.
+ */
+export const readImproveKitAssets = async (args) => {
+    const document = args.document ?? await readJson(args.layerDocPath);
+    const layerDocPresent = document !== undefined;
+    const canvas = canvasOf(document);
+    const assetsDir = `${args.layerDocPath}.assets`;
+    const manifest = await readJson(path.join(assetsDir, 'manifest.json'));
+    const declared = isRecord(manifest) && Array.isArray(manifest.artifacts)
+        ? manifest.artifacts
+        : [];
+    const names = await readdir(assetsDir).catch(() => []);
+    const leaves = flattenLayerDoc(document);
+    const ownerById = new Map();
+    leaves.forEach((leaf, index) => {
+        for (const { key, id } of artifactIdsOf(leaf)) {
+            if (!ownerById.has(id))
+                ownerById.set(id, { leaf, index, key });
+        }
+    });
+    const assets = [];
+    for (const artifact of declared) {
+        const id = typeof artifact.id === 'string' ? artifact.id : undefined;
+        if (!id)
+            continue;
+        const resolved = await resolveAssetFile({ id, localPath: artifact.localPath, assetsDir, names });
+        const owner = ownerById.get(id);
+        const box = owner ? boxOfLeaf(owner.leaf) : undefined;
+        const bounds = box && canvas ? boundsPct(box, canvas) : undefined;
+        const coverage = bounds ? (bounds.width / 100) * (bounds.height / 100) : undefined;
+        const role = assetRole(id, artifact.role);
+        assets.push({
+            id,
+            file: path.relative(args.runDir, resolved.absolute),
+            role,
+            roleLabel: IMPROVE_ASSET_ROLE_COPY[role].label,
+            instruction: IMPROVE_ASSET_ROLE_COPY[role].instruction,
+            ...(owner ? { layer: { kind: owner.leaf.kind ?? 'layer', name: layerName(owner.leaf), index: owner.index } } : {}),
+            ...(bounds ? { bounds } : {}),
+            ...(coverage === undefined ? {} : { coverage }),
+            hero: coverage !== undefined && coverage >= IMPROVE_HERO_COVERAGE,
+            present: resolved.present,
+            ship: dispositionByRole(role),
+        });
+    }
+    assets.sort((left, right) => ((right.coverage ?? -1) - (left.coverage ?? -1) || left.id.localeCompare(right.id)));
+    const byId = new Map(assets.map((asset) => [asset.id, asset]));
+    const rasterLayers = [];
+    leaves.forEach((leaf, index) => {
+        const ids = artifactIdsOf(leaf);
+        if (ids.length === 0)
+            return;
+        const box = boxOfLeaf(leaf);
+        if (!box || !canvas)
+            return;
+        const bounds = boundsPct(box, canvas);
+        const coverage = (bounds.width / 100) * (bounds.height / 100);
+        const carried = ids.map(({ id }) => byId.get(id)).filter((asset) => Boolean(asset));
+        rasterLayers.push({
+            index,
+            kind: leaf.kind ?? 'layer',
+            name: layerName(leaf),
+            bounds,
+            coverage,
+            hero: coverage >= IMPROVE_HERO_COVERAGE,
+            ...(carried[0] ? { asset: carried[0] } : {}),
+            alternates: carried.slice(1),
+        });
+    });
+    rasterLayers.sort((left, right) => right.coverage - left.coverage || left.index - right.index);
+    // The LayerDoc settles it: the carrier a layer names is the file to ship, and
+    // every other artifact of that layer is an alternate resolution of it.
+    for (const layer of rasterLayers) {
+        if (layer.asset)
+            layer.asset.ship = 'ship';
+        for (const alternate of layer.alternates)
+            alternate.ship = 'alternate resolution';
+    }
+    classifyCleanPlates({ assets, rasterLayers });
+    return {
+        ...(canvas ? { canvas } : {}),
+        assets,
+        rasterLayers,
+        layerDocPresent,
+        manifestPresent: declared.length > 0,
+    };
+};
+//# sourceMappingURL=improve-kit-assets.js.map

package/dist/improve-kit-assets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"improve-kit-assets.js","sourceRoot":"","sources":["../src/improve-kit-assets.ts"],"names":[],"mappings":"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"}

package/dist/improve-kit-ignore.d.ts

@@ -0,0 +1,32 @@
+export declare const IMPROVE_GITIGNORE_PATTERN = ".improve/";
+export declare const IMPROVE_GITIGNORE_COMMENT = "# 12ui improve kits: candidates, captures and targets are not source";
+export type ImproveKitIgnoreState = 
+/** This run appended the rule to the repository root `.gitignore`. */
+'ignored'
+/** Some pattern already ignored the out-dir; nothing was written. */
+ | 'already-ignored'
+/** Inside a repository, not ignored, and not a kit directory this may claim. */
+ | 'not-ignored';
+export type ImproveKitIgnore = {
+    state: ImproveKitIgnoreState;
+    /** The out-dir relative to the repository root, in POSIX form. */
+    relativeOutDir: string;
+};
+/**
+ * Decide, and where it is safe, act. Returns `undefined` when the out-dir is not
+ * inside a git working tree — the common case, and the one where the CLI has
+ * nothing to say.
+ *
+ * Only the repository ROOT `.gitignore` is ever written, only by appending, and
+ * only when the out-dir is named `.improve` or lives under one. Anything else
+ * gets the advisory line instead: guessing a pattern for an arbitrary directory
+ * could ignore a lane's source.
+ */
+export declare const ensureImproveKitIgnored: (args: {
+    outDir: string;
+}) => Promise<ImproveKitIgnore | undefined>;
+/** The one line a run prints when the kit is committable and nobody said so. */
+export declare const improveKitIgnoreNote: (kit: ImproveKitIgnore | undefined) => string | undefined;
+/** The same fact, in the kit's own status block. */
+export declare const improveKitIgnoreStatusLine: (kit: ImproveKitIgnore | undefined) => string | undefined;
+//# sourceMappingURL=improve-kit-ignore.d.ts.map

package/dist/improve-kit-ignore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"improve-kit-ignore.d.ts","sourceRoot":"","sources":["../src/improve-kit-ignore.ts"],"names":[],"mappings":"AAwBA,eAAO,MAAM,yBAAyB,cAAc,CAAC;AACrD,eAAO,MAAM,yBAAyB,yEACkC,CAAC;AAEzE,MAAM,MAAM,qBAAqB;AAC/B,sEAAsE;AACpE,SAAS;AACX,qEAAqE;GACnE,iBAAiB;AACnB,gFAAgF;GAC9E,aAAa,CAAC;AAElB,MAAM,MAAM,gBAAgB,GAAG;IAC7B,KAAK,EAAE,qBAAqB,CAAC;IAC7B,kEAAkE;IAClE,cAAc,EAAE,MAAM,CAAC;CACxB,CAAC;AAmDF;;;;;;;;;GASG;AACH,eAAO,MAAM,uBAAuB,GAAU,MAAM;IAClD,MAAM,EAAE,MAAM,CAAC;CAChB,KAAG,OAAO,CAAC,gBAAgB,GAAG,SAAS,CAmBvC,CAAC;AAEF,gFAAgF;AAChF,eAAO,MAAM,oBAAoB,GAAI,KAAK,gBAAgB,GAAG,SAAS,KAAG,MAAM,GAAG,SAKjF,CAAC;AAEF,oDAAoD;AACpD,eAAO,MAAM,0BAA0B,GAAI,KAAK,gBAAgB,GAAG,SAAS,KAAG,MAAM,GAAG,SAMvF,CAAC"}

package/dist/improve-kit-ignore.js

@@ -0,0 +1,111 @@
+import { execFile } from 'node:child_process';
+import { readFile, stat, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { promisify } from 'node:util';
+/**
+ * Keep the kit out of the repository's history (F17).
+ *
+ * `--out-dir .improve/<surface>` puts winner PNGs, every candidate, the capture
+ * sources and the whole target asset tree inside the repo being improved — about
+ * 100 MB of paid artifacts. Nothing said not to commit them, so one wave-2 lane's
+ * `git add -A` swept 102 kit files (100.8 MiB) into a seed commit, and the other
+ * three lanes each invented the same `.gitignore` rule for themselves. A rule
+ * four readers have to invent is a rule the tool owes them.
+ *
+ * The kit stays advisory: it appends one line when the out-dir is unambiguously a
+ * kit directory, says so plainly when it is not, and never fails the run.
+ */
+const execFileAsync = promisify(execFile);
+/** The directory name that makes an out-dir unambiguously a kit, not source. */
+const IMPROVE_KIT_DIRECTORY = '.improve';
+export const IMPROVE_GITIGNORE_PATTERN = '.improve/';
+export const IMPROVE_GITIGNORE_COMMENT = '# 12ui improve kits: candidates, captures and targets are not source';
+const exists = async (file) => (stat(file).then(() => true).catch(() => false));
+/**
+ * The repository the out-dir actually sits in, which is not necessarily
+ * `--repo`: a lane can point `--repo` at a package and write the kit above it.
+ * A `.git` file (worktree, submodule) counts exactly like a `.git` directory.
+ */
+const repositoryRoot = async (from) => {
+    let directory = path.resolve(from);
+    for (;;) {
+        if (await exists(path.join(directory, '.git')))
+            return directory;
+        const parent = path.dirname(directory);
+        if (parent === directory)
+            return undefined;
+        directory = parent;
+    }
+};
+const LITERAL_PATTERNS = new Set(['.improve', '.improve/', '/.improve', '/.improve/']);
+/** The fallback when git cannot be run at all: does the root file say it already? */
+const literallyIgnored = async (gitignore) => {
+    const text = await readFile(gitignore, 'utf8').catch(() => '');
+    return text.split('\n').some((line) => LITERAL_PATTERNS.has(line.trim()));
+};
+/** `true`/`false` from git itself; `undefined` when git could not answer. */
+const gitIgnores = async (root, relative) => {
+    try {
+        await execFileAsync('git', ['check-ignore', '-q', '--', relative], { cwd: root });
+        return true;
+    }
+    catch (error) {
+        return error.code === 1 ? false : undefined;
+    }
+};
+const appendRule = async (gitignore) => {
+    const existing = await readFile(gitignore, 'utf8').catch(() => undefined);
+    const separator = existing === undefined || existing.length === 0
+        ? ''
+        : existing.endsWith('\n') ? '\n' : '\n\n';
+    await writeFile(gitignore, `${existing ?? ''}${separator}${IMPROVE_GITIGNORE_COMMENT}\n${IMPROVE_GITIGNORE_PATTERN}\n`, 'utf8');
+};
+/**
+ * Decide, and where it is safe, act. Returns `undefined` when the out-dir is not
+ * inside a git working tree — the common case, and the one where the CLI has
+ * nothing to say.
+ *
+ * Only the repository ROOT `.gitignore` is ever written, only by appending, and
+ * only when the out-dir is named `.improve` or lives under one. Anything else
+ * gets the advisory line instead: guessing a pattern for an arbitrary directory
+ * could ignore a lane's source.
+ */
+export const ensureImproveKitIgnored = async (args) => {
+    try {
+        const outDir = path.resolve(args.outDir);
+        const root = await repositoryRoot(outDir);
+        if (!root || root === outDir)
+            return undefined;
+        const relative = path.relative(root, outDir).split(path.sep).join('/');
+        if (!relative || relative.startsWith('../'))
+            return undefined;
+        const gitignore = path.join(root, '.gitignore');
+        const ignored = await gitIgnores(root, relative) ?? await literallyIgnored(gitignore);
+        if (ignored)
+            return { state: 'already-ignored', relativeOutDir: relative };
+        if (!relative.split('/').includes(IMPROVE_KIT_DIRECTORY)) {
+            return { state: 'not-ignored', relativeOutDir: relative };
+        }
+        await appendRule(gitignore);
+        return { state: 'ignored', relativeOutDir: relative };
+    }
+    catch {
+        // Advisory work never sinks a run that has already spent money.
+        return undefined;
+    }
+};
+/** The one line a run prints when the kit is committable and nobody said so. */
+export const improveKitIgnoreNote = (kit) => (kit?.state === 'not-ignored'
+    ? 'The kit is inside the repository and is not git-ignored;'
+        + ` add ${kit.relativeOutDir}/ to .gitignore before committing.`
+    : undefined);
+/** The same fact, in the kit's own status block. */
+export const improveKitIgnoreStatusLine = (kit) => {
+    if (!kit)
+        return undefined;
+    return kit.state === 'not-ignored'
+        ? `Kit: not git-ignored — see the note; add \`${kit.relativeOutDir}/\` to .gitignore`
+            + ' before committing.'
+        : 'Kit: git-ignored via .gitignore.';
+};
+//# sourceMappingURL=improve-kit-ignore.js.map

package/dist/improve-kit-ignore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"improve-kit-ignore.js","sourceRoot":"","sources":["../src/improve-kit-ignore.ts"],"names":[],"mappings":"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"}

package/dist/improve-kit-readme.d.ts

@@ -1,3 +1,12 @@
-import type { ImproveRecord } from './improve-workspace.js';
-export declare const writeImproveReadme: (record: ImproveRecord) => Promise<string>;
+import { type ImproveKitAssetIndex } from './improve-kit-assets.js';
+import { type ImproveKitStatus } from './improve-kit-status.js';
+import { type ImproveRecord, type ImproveStage } from './improve-workspace.js';
+export declare const renderImproveReadme: (args: {
+    record: ImproveRecord;
+    status: ImproveKitStatus;
+    index: ImproveKitAssetIndex;
+}) => string;
+export declare const writeImproveReadme: (record: ImproveRecord, context?: {
+    requestedTo?: ImproveStage;
+}) => Promise<string>;
 //# sourceMappingURL=improve-kit-readme.d.ts.map

package/dist/improve-kit-readme.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"improve-kit-readme.d.ts","sourceRoot":"","sources":["../src/improve-kit-readme.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAE5D,eAAO,MAAM,kBAAkB,GAAU,QAAQ,aAAa,KAAG,OAAO,CAAC,MAAM,CA4B9E,CAAC"}
+{"version":3,"file":"improve-kit-readme.d.ts","sourceRoot":"","sources":["../src/improve-kit-readme.ts"],"names":[],"mappings":"AAGA,OAAO,EAOL,KAAK,oBAAoB,EAC1B,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAOL,KAAK,gBAAgB,EACtB,MAAM,yBAAyB,CAAC;AAIjC,OAAO,EAAgB,KAAK,aAAa,EAAE,KAAK,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAwT7F,eAAO,MAAM,mBAAmB,GAAI,MAAM;IACxC,MAAM,EAAE,aAAa,CAAC;IACtB,MAAM,EAAE,gBAAgB,CAAC;IACzB,KAAK,EAAE,oBAAoB,CAAC;CAC7B,KAAG,MAmBQ,CAAC;AAEb,eAAO,MAAM,kBAAkB,GAC7B,QAAQ,aAAa,EACrB,UAAS;IAAE,WAAW,CAAC,EAAE,YAAY,CAAA;CAAO,KAC3C,OAAO,CAAC,MAAM,CAQhB,CAAC"}