@hajimism/dek 0.3.1 → 0.3.3

package/CHANGELOG.md

@@ -2,6 +2,52 @@
 
 Release notes for `@hajimism/dek`. From 0.1.0 on, release-please writes this file from the Conventional Commits on `main`.
 
+## [0.3.3](https://github.com/hajimism/dek/compare/v0.3.2...v0.3.3) (2026-10-21)
+
+
+### Features
+
+* **new:** start a deck on a ref's theme with `--theme-from <ref>` ([6d0ffc9](https://github.com/hajimism/dek/commit/6d0ffc9c45a54092375ca73e305294e71e005655))
+* **new:** start a deck on a ref's theme with `--theme-from <ref>` ([54be6db](https://github.com/hajimism/dek/commit/54be6db71b2521fda1bec3ddb967a4a7545bc36c))
+* **pack:** hand a deck over under CC0 1.0 unless dek.toml says otherwise ([b7e2565](https://github.com/hajimism/dek/commit/b7e2565fd83a8d82c8d8416f6ae3551ba5040427))
+* **pack:** hand a deck over under CC0 1.0 unless dek.toml says otherwise ([46cd7b9](https://github.com/hajimism/dek/commit/46cd7b9424d9e76570c2e017f2345b41f85506b3))
+* **ref:** hand a deck over with `dekc pack` and read it with `dekc ref <file>.tgz` ([9e77bbc](https://github.com/hajimism/dek/commit/9e77bbc7bdf9f2e232c115903c73bf8fa8f078fe))
+* **ref:** hand a deck over with `dekc pack` and read it with `dekc ref <file>.tgz` ([a0c67bc](https://github.com/hajimism/dek/commit/a0c67bc8258a2132dd77eadb2b87c838e6e9f866))
+
+
+### Bug Fixes
+
+* **dev:** leave the Enter and Escape that end a conversion to the input method ([f148c54](https://github.com/hajimism/dek/commit/f148c54377460b4df11e8fedd059554f00c06889))
+* **dev:** leave the Enter and Escape that end a conversion to the input method ([e2b3940](https://github.com/hajimism/dek/commit/e2b3940cf48168b5a7c2b95250df982566222b60))
+
+
+### Documentation
+
+* **adr:** hand a deck over as a pack and read it as a ref ([4b3ffc6](https://github.com/hajimism/dek/commit/4b3ffc6e653757f3976a581acff1a2bf76862748))
+* **adr:** start a deck from a ref's theme ([f836941](https://github.com/hajimism/dek/commit/f836941cb2faf9b33faaab63abd16f66878e4767))
+* describe packs in the structure guide, the reference, and ADR 15 ([020d4a0](https://github.com/hajimism/dek/commit/020d4a0254138c55e0a78c41e2e28f8a839bf8d1))
+* record the pack's license in ADR 16, the guide, and the reference ([a0b4ea7](https://github.com/hajimism/dek/commit/a0b4ea74b6d896d102c1c0e2c06a040b75905962))
+* say a deck can start on a ref's theme, in the guides and the reference ([49791ff](https://github.com/hajimism/dek/commit/49791ff46f77e5fd37e9d21f4061669de31af1f9))
+
+## [0.3.2](https://github.com/hajimism/dek/compare/v0.3.1...v0.3.2) (2026-10-20)
+
+
+### Bug Fixes
+
+* **pdf:** print each slide as a picture with its text laid over it ([02f49a8](https://github.com/hajimism/dek/commit/02f49a855209e1c4430613fd9358699305bcbb9b))
+* **pdf:** print each slide as a picture with its text laid over it ([b88259d](https://github.com/hajimism/dek/commit/b88259dbcc80ed0a1450cc6bf6422c71120c5802))
+
+
+### Performance
+
+* **pdf:** keep a slide of photographs as a JPEG ([19a9092](https://github.com/hajimism/dek/commit/19a909214b256c8bbcf66a443f00c54c2b43766e))
+
+
+### Documentation
+
+* record the PDF as pictures in ADR 14 and the presenting guide ([c889781](https://github.com/hajimism/dek/commit/c88978175a9b3812f611d8af4de94b2de57556c1))
+* say which slides the PDF keeps as JPEGs, in ADR 14 and the guide ([de733fb](https://github.com/hajimism/dek/commit/de733fb4589d5f6f45f6f9a83b60673d2feab706))
+
 ## [0.3.1](https://github.com/hajimism/dek/compare/v0.3.0...v0.3.1) (2026-10-08)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hajimism/dek",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "description": "A build system for talks.",
   "license": "MIT",
   "author": "Hajime Nakagawa (https://github.com/hajimism)",
@@ -61,11 +61,11 @@
     "zod": "^4.6.5"
   },
   "devDependencies": {
-    "@biomejs/biome": "2.5.14",
-    "@happy-dom/global-registrator": "20.14.5",
+    "@biomejs/biome": "2.5.15",
+    "@happy-dom/global-registrator": "21.0.1",
     "@types/bun": "^1.4.2",
-    "happy-dom": "20.14.5",
-    "knip": "6.38.0",
+    "happy-dom": "21.0.1",
+    "knip": "6.41.0",
     "playwright": "^1.63.0",
     "typescript": "^7.0.2",
     "vitepress": "^1.6.4"

package/src/cli/commands.ts

@@ -1,4 +1,5 @@
 import { hasErrors } from "../core/diagnostic.ts";
+import { isRefName } from "../core/ref-name.ts";
 import { mergeSarif, toSarif } from "../core/sarif.ts";
 import type { CheckCliResult } from "./check.ts";
 import type { ResultFields } from "./contract.ts";
@@ -21,6 +22,7 @@ import {
   formatMv,
   formatNav,
   formatNew,
+  formatPack,
   formatPdf,
   formatRef,
   formatReport,
@@ -266,14 +268,22 @@ export const COMMANDS = {
   new: result({
     args: ["name"],
     flags: ["theme-from"],
-    usage: ["dekc new <name> [--theme-from DECK]"],
-    summary: "Add a deck with the project's theme, or another deck's, and its skeleton slides.",
+    usage: ["dekc new <name> [--theme-from DECK|REF]"],
+    summary:
+      "Add a deck with the project's theme, another deck's, or a ref's, and its skeleton slides.",
     group: "Project",
-    overview: [["dekc new <name> [--theme-from DECK]", "add a deck"]],
-    agent: ["dekc new <name> [--theme-from DECK]"],
+    overview: [["dekc new <name> [--theme-from DECK|REF]", "add a deck"]],
+    agent: [
+      "dekc new <name> [--theme-from DECK|REF]   a ref's theme to build on its layouts; copied, never linked",
+    ],
     run: async ({ cwd, args, flags }) => {
+      const themeFrom = flags["theme-from"];
       const { newCommand } = await import("./new.ts");
-      return newCommand({ cwd, name: args.name, themeFrom: flags["theme-from"] });
+      if (themeFrom !== undefined && isRefName(themeFrom)) {
+        const { restoreRef } = await import("./ref.ts");
+        await restoreRef(cwd, themeFrom);
+      }
+      return newCommand({ cwd, name: args.name, themeFrom });
     },
     output: {
       text: formatNew,
@@ -313,7 +323,7 @@ export const COMMANDS = {
   ref: result({
     args: ["source?"],
     flags: [],
-    usage: ["dekc ref <owner/repo/deck>[@rev]", "dekc ref"],
+    usage: ["dekc ref <owner/repo/deck>[@rev]", "dekc ref <file>.tgz", "dekc ref"],
     summary:
       "Pin another project's deck to read as a model, list the pins, or drop one.\nls, show, theme, and shot read a ref as they read a deck.",
     group: "Refs",
@@ -322,11 +332,13 @@ export const COMMANDS = {
         "dekc ref owner/repo/deck[@rev]",
         "pin and fetch one (a GitHub link works too); again moves the pin",
       ],
+      ["dekc ref <file>.tgz", "pin a pack someone sent as file/<deck>; commit packs/"],
       ["dekc ref", "list pinned refs"],
       ["dekc ref rm <ref>", "drop one"],
     ],
     agent: [
       "dekc ref [owner/repo/deck[@rev] | github-link]   pin + fetch; no args lists; dekc ref rm <ref>",
+      "dekc ref <file>.tgz  pin a pack as file/<deck>; commit packs/<deck>.tgz, which a clone unpacks",
     ],
     run: async ({ cwd, args }) => {
       const { addRef, listRefs } = await import("./ref.ts");
@@ -343,7 +355,31 @@ export const COMMANDS = {
         },
       },
     },
-    output: { text: formatRef },
+    output: {
+      text: formatRef,
+      paths: (data, display) =>
+        data.action === "add" && data.pack !== undefined
+          ? { ...data, pack: display(data.pack) }
+          : data,
+    },
+  }),
+  pack: result({
+    scope: "decks",
+    args: [],
+    flags: ["root-dist"],
+    usage: ["dekc pack [deck] [--root-dist]"],
+    summary:
+      "Write dist/<deck>.tgz: the deck as a file to hand to someone who reads it as a ref with\n`dekc ref <file>.tgz`, without access to where it lives.",
+    group: "Refs",
+    overview: [["dekc pack [--root-dist]", "write the deck as a file for `dekc ref` elsewhere"]],
+    agent: [
+      "dekc pack [--root-dist]   dist/<deck>.tgz, for another project's `dekc ref <file>.tgz`",
+    ],
+    run: async ({ target, flags }) => {
+      const { packCommand } = await import("./pack.ts");
+      return packCommand(target, { rootDist: flags["root-dist"] });
+    },
+    output: { text: formatPack },
   }),
   show: result({
     scope: "deck",
@@ -774,7 +810,8 @@ export const COMMANDS = {
     args: [],
     flags: ["root-dist"],
     usage: ["dekc pdf [deck] [--root-dist]"],
-    summary: "Write dist/<deck>.pdf, one page per slide at its last beat. Needs Playwright.",
+    summary:
+      "Write dist/<deck>.pdf, one page per slide at its last beat: a picture of it with its text\nlaid over it, unseen, to select and search. Needs Playwright.",
     group: "Output",
     overview: [["dekc pdf [--root-dist]", "write a PDF"]],
     agent: ["dekc pdf [--root-dist]"],

package/src/cli/contract.ts

@@ -111,6 +111,7 @@ export const RESULT_FIELDS = {
     created: paths,
     updated: paths,
     next: z.array(z.string()),
+    warnings: z.array(z.string()).describe("Set when the theme came from a ref with no license."),
   }),
   ls: z.union([
     z.strictObject({
@@ -159,6 +160,10 @@ export const RESULT_FIELDS = {
       changed: z.boolean(),
       dir: z.string(),
       license: z.string().nullable(),
+      pack: z
+        .string()
+        .optional()
+        .describe("A pack's ref: the copy in packs/ to commit, which a clone unpacks it from."),
       warnings: z.array(z.string()),
     }),
     z.strictObject({
@@ -413,6 +418,10 @@ export const RESULT_FIELDS = {
   }),
   pdf: z.strictObject({ outs: paths }),
   pptx: z.strictObject({ outs: paths }),
+  pack: z.strictObject({
+    outs: paths,
+    warnings: z.array(z.string()).describe("Once per project: the packs carry no license."),
+  }),
 } satisfies Record<ResultCommand, FieldsSchema>;
 
 type FieldsSchema = z.ZodObject | z.ZodUnion<readonly z.ZodObject[]>;

package/src/cli/files.ts

@@ -14,7 +14,14 @@ export function defaultTheme(): string {
 }
 
 export function defaultToml(): string {
-  return "# dek project\n";
+  return `# dek project
+
+[pack]
+# The license \`dekc pack\` hands a deck over under. CC0-1.0 lets the reader reuse it
+# freely, with no credit owed, as a template is meant to be used; CC-BY-4.0 asks for
+# credit. Delete the line to hand decks over with no license.
+license = "CC0-1.0"
+`;
 }
 
 /**

package/src/cli/new.ts

@@ -4,9 +4,10 @@ import { loadConfig } from "../core/config.ts";
 import { deckPaths } from "../core/deck-paths.ts";
 import { DekError } from "../core/error.ts";
 import { DECK_NAME_HINT, isDeckName } from "../core/path.ts";
+import { isRefName } from "../core/ref-name.ts";
 import { syncDeck } from "../core/sync.ts";
 import { applyPlan, deckPlan, nextSteps } from "./files.ts";
-import { requireDeckFromCwd, requireProject } from "./scope.ts";
+import { type RefInfo, requireDeckFromCwd, requireProject, resolveTarget } from "./scope.ts";
 
 export type NewResult = {
   name: string;
@@ -16,6 +17,8 @@ export type NewResult = {
   updated: string[];
   /** The commands to run next, from the directory new ran in. */
   next: string[];
+  /** Set when the theme came from a ref with no license. */
+  warnings: string[];
 };
 
 export function newCommand(options: { cwd: string; name: string; themeFrom?: string }): NewResult {
@@ -35,19 +38,29 @@ export function newCommand(options: { cwd: string; name: string; themeFrom?: str
     });
   }
 
-  const themeSource = options.themeFrom
-    ? deckPaths(requireDeckFromCwd(options.cwd, options.themeFrom).deck.dir).theme
-    : join(project.root, "theme.css");
+  // A ref is read where it is, never written: only the copy below is the new deck's.
+  const fromRef =
+    options.themeFrom !== undefined && isRefName(options.themeFrom)
+      ? resolveTarget(options.cwd, "deck", { refs: true, deck: options.themeFrom })
+      : undefined;
+  const ref = fromRef?.ref;
+  const themeSource = fromRef
+    ? deckPaths(fromRef.deck.dir).theme
+    : options.themeFrom
+      ? deckPaths(requireDeckFromCwd(options.cwd, options.themeFrom).deck.dir).theme
+      : join(project.root, "theme.css");
   if (!existsSync(themeSource)) {
     throw new DekError("theme.css not found", {
       path: themeSource,
-      hint: options.themeFrom
-        ? "run `dekc ls` and pick a deck that has theme.css"
-        : "add theme.css at the project root",
+      hint: ref
+        ? "run `dekc ref` to list the refs, and pick one whose deck has theme.css"
+        : options.themeFrom
+          ? "run `dekc ls` and pick a deck that has theme.css"
+          : "add theme.css at the project root",
     });
   }
 
-  const theme = readFileSync(themeSource, "utf8");
+  const theme = `${ref ? provenance(ref) : ""}${readFileSync(themeSource, "utf8")}`;
   const { created } = applyPlan(
     deckPlan(project.root, name, theme, loadConfig(project.configPath)),
   );
@@ -61,5 +74,16 @@ export function newCommand(options: { cwd: string; name: string; themeFrom?: str
     created,
     updated: synced.dekFiles.updated,
     next: nextSteps(options.cwd, project.root, dir),
+    warnings:
+      ref && ref.license === null
+        ? [
+            `${ref.name} has no license; ask its author before you present or share a deck built on its theme`,
+          ]
+        : [],
   };
 }
+
+/** The first line of a theme copied from a ref: where it came from, for its reader and its credit. */
+function provenance(ref: RefInfo): string {
+  return `/* Theme from the ref ${ref.name} at ${ref.rev.slice(0, 7)}. */\n`;
+}

package/src/cli/pack.ts

@@ -0,0 +1,21 @@
+import { writePack } from "../core/pack.ts";
+import type { DecksTarget } from "./scope.ts";
+
+/** One file per deck, a single deck included, as `dekc pdf` answers, and what to fix first. */
+export type PackCliResult = { outs: string[]; warnings: string[] };
+
+export async function packCommand(
+  { project, decks }: DecksTarget,
+  options: { rootDist?: boolean } = {},
+): Promise<PackCliResult> {
+  const outs: string[] = [];
+  const warnings = new Set<string>();
+  for (const entry of decks) {
+    const done = await writePack(project, entry, { rootDist: options.rootDist });
+    outs.push(done.outPath);
+    for (const warning of done.warnings) {
+      warnings.add(warning);
+    }
+  }
+  return { outs, warnings: [...warnings] };
+}

package/src/cli/ref.ts

@@ -1,20 +1,27 @@
 import { existsSync, lstatSync, readdirSync, readFileSync, rmdirSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { dirname, join, resolve } from "node:path";
 import { loadConfig } from "../core/config.ts";
 import { DekError } from "../core/error.ts";
 import { downloadTarball, resolveRev } from "../core/github.ts";
 import {
+  deckOfPack,
   installSnapshot,
   isPinnedRev,
+  packFile,
   parseRefSource,
-  type RefSource,
+  pickSnapshot,
+  readPack,
   readTarball,
   refLicense,
   refState,
   refTitle,
+  type Snapshot,
+  snapshotDigest,
+  writeSnapshot,
 } from "../core/ref.ts";
+import type { FileRefSource, GithubRefSource } from "../core/ref-name.ts";
 import { readTextIfExists } from "../core/resolve.ts";
-import { readSourceIfExists, removeInside, writeInside } from "../core/safe-fs.ts";
+import { readSourceIfExists, removeInside, requireInside, writeInside } from "../core/safe-fs.ts";
 import { writeAgentsMd } from "../core/sync.ts";
 import { setTableKey } from "../core/toml-keys.ts";
 import { requireProject } from "./scope.ts";
@@ -29,6 +36,8 @@ export type RefAddResult = {
   changed: boolean;
   dir: string;
   license: string | null;
+  /** A pack's ref: its committed copy, which a clone unpacks the ref from. */
+  pack?: string;
   warnings: string[];
 };
 
@@ -53,17 +62,71 @@ export async function restoreRef(cwd: string, arg: string): Promise<void> {
   if (pinned === undefined || fetched) {
     return;
   }
+  if (source.kind === "file") {
+    await unpackSnapshot(project.root, source, pinned);
+    return;
+  }
   await fetchSnapshot(project.root, source, pinned);
 }
 
-async function fetchSnapshot(root: string, source: RefSource, sha: string) {
+async function fetchSnapshot(root: string, source: GithubRefSource, sha: string) {
   const files = await readTarball(await downloadTarball(source.owner, source.repo, sha));
   return installSnapshot(root, source, sha, files);
 }
 
+/** A pack's snapshot, unpacked again from its committed copy, which must be the pinned one. */
+async function unpackSnapshot(root: string, source: FileRefSource, pin: string): Promise<void> {
+  const rel = packFile(source.deck);
+  const path = join(root, rel);
+  if (!existsSync(path)) {
+    throw new DekError(`${rel} is missing`, {
+      path,
+      hint: `a pack's ref is unpacked from its copy in packs/, so commit packs/ with dek.toml; run \`dekc ref <file>.tgz\` with the pack you were sent to add it again`,
+    });
+  }
+  const snapshot = await readPackFile(path, source, root);
+  if ((await snapshotDigest(snapshot)) !== pin) {
+    throw new DekError(`${rel} is not the pack ${source.name} is pinned to`, {
+      path,
+      hint: `run \`dekc ref ${rel}\` to pin the pack that is there, or put back the one dek.toml pins`,
+    });
+  }
+  await writeSnapshot(root, source.name, pin, snapshot);
+}
+
+/** What a snapshot keeps of the pack at `path`; an error says which file it was about. */
+async function readPackFile(
+  path: string,
+  source: FileRefSource | undefined,
+  root?: string,
+): Promise<Snapshot & { source: FileRefSource; bytes: Uint8Array }> {
+  try {
+    const bytes = readFileSync(root === undefined ? path : requireInside(path, root));
+    const files = await readPack(bytes);
+    const found = source ?? parseRefSource(`file/${deckOfPack(files)}`);
+    if (found.kind !== "file") {
+      throw new DekError("the pack's deck cannot be named as a ref");
+    }
+    return { ...pickSnapshot(files, found), source: found, bytes };
+  } catch (error) {
+    if (error instanceof DekError && error.path === undefined) {
+      throw new DekError(error.message, { path, ...(error.hint ? { hint: error.hint } : {}) });
+    }
+    throw error;
+  }
+}
+
 /** `dekc ref <source>`: pin and fetch, or move the pin to the latest or to the rev after `@`. */
 export async function addRef(cwd: string, arg: string): Promise<RefAddResult> {
+  if (isPackPath(arg)) {
+    return addPack(cwd, arg);
+  }
   const source = parseRefSource(arg);
+  if (source.kind === "file") {
+    throw new DekError(`"${arg}" names a pack's ref`, {
+      hint: "add a pack by its file, `dekc ref <file>.tgz`; `dekc ref` lists the refs already added",
+    });
+  }
   const project = requireProject(cwd);
   const { pinned: from, dir, fetched } = refState(project, source.name);
   const rev =
@@ -103,6 +166,84 @@ export async function addRef(cwd: string, arg: string): Promise<RefAddResult> {
   };
 }
 
+/** An argument that ends in .tgz or .tar.gz is a pack's path, never a ref name. */
+function isPackPath(arg: string): boolean {
+  return /\.(tgz|tar\.gz)$/i.test(arg);
+}
+
+/**
+ * `dekc ref <file>.tgz`: pin the pack's deck as `file/<deck>` to the digest of its files, keep
+ * the pack as packs/<deck>.tgz for git, and unpack the snapshot. Everything is read and checked
+ * before the first write.
+ */
+async function addPack(cwd: string, arg: string): Promise<RefAddResult> {
+  const project = requireProject(cwd);
+  const given = resolve(cwd, arg);
+  if (!existsSync(given)) {
+    throw new DekError(`no such file: ${arg}`, {
+      path: given,
+      hint: "pass the path of the .tgz `dekc pack` wrote",
+    });
+  }
+  const read = await readPackFile(given, undefined);
+  const { source, bytes } = read;
+  const rev = await snapshotDigest(read);
+  const { pinned: from, dir, fetched } = refState(project, source.name);
+  const stored = join(project.root, packFile(source.deck));
+
+  let changed = false;
+  if (!(fetched && from === rev)) {
+    await writeSnapshot(project.root, source.name, rev, read);
+    changed = true;
+  }
+  if (!(await isPackOf(stored, source, rev, project.root))) {
+    writeInside(stored, bytes, project.root);
+    changed = true;
+  }
+  if (from !== rev) {
+    const toml = readTextIfExists(project.configPath) ?? "";
+    writeInside(project.configPath, setTableKey(toml, "refs", source.name, rev), project.root);
+    changed = true;
+  }
+  ignoreRefs(project.root);
+  writeAgentsMd(project.root);
+
+  const license = refLicense(dir);
+  return {
+    action: "add",
+    name: source.name,
+    rev,
+    ...(from !== undefined && from !== rev ? { from } : {}),
+    changed,
+    dir,
+    license,
+    pack: stored,
+    warnings:
+      license === null
+        ? [
+            "the pack has no license; read it as a model, but ask its author before reusing its text or assets",
+          ]
+        : [],
+  };
+}
+
+/** True when the pack at `path` holds the files `rev` pins. */
+async function isPackOf(
+  path: string,
+  source: FileRefSource,
+  rev: string,
+  root: string,
+): Promise<boolean> {
+  if (!existsSync(path)) {
+    return false;
+  }
+  try {
+    return (await snapshotDigest(await readPackFile(path, source, root))) === rev;
+  } catch {
+    return false;
+  }
+}
+
 export function listRefs(cwd: string): RefListResult {
   const project = requireProject(cwd);
   const refs = Object.keys(loadConfig(project.configPath).refs ?? {}).map((name) => {
@@ -133,6 +274,17 @@ export function removeRef(cwd: string, arg: string): RefRmResult {
   }
   removeInside(dir, project.root, { recursive: true });
   removeEmptyParents(dirname(dir), project.root);
+  if (source.kind === "file") {
+    const packs = join(project.root, "packs");
+    removeInside(join(project.root, packFile(source.deck)), project.root);
+    if (
+      existsSync(packs) &&
+      !lstatSync(packs).isSymbolicLink() &&
+      readdirSync(packs).length === 0
+    ) {
+      rmdirSync(packs);
+    }
+  }
   writeAgentsMd(project.root);
   return { action: "rm", name: source.name };
 }

package/src/cli/scope.ts

@@ -3,6 +3,7 @@ import { join } from "node:path";
 import { DekError } from "../core/error.ts";
 import {
   isRefName,
+  packFile,
   parseRefSource,
   REF_MARKER,
   readRefMeta,
@@ -139,7 +140,7 @@ export function resolveScope(cwd: string, options: { deck?: string } = {}): Scop
   }
   if (isRefName(name)) {
     throw new DekError(`"${name}" is a ref; refs are read-only`, {
-      hint: `read it with \`dekc show ${name} <slug>\`, then copy what you need into your own deck and rewrite it in your theme`,
+      hint: `start a deck on its theme with \`dekc new <name> --theme-from ${name}\`, or read it with \`dekc show ${name} <slug>\` and write what you need in your own deck's theme`,
     });
   }
   const deck = project.decks.find((entry) => entry.name === name);
@@ -273,10 +274,18 @@ function resolveRef(cwd: string, arg: string): ReadableDeck & { ref: RefInfo } {
   if (pinned === undefined) {
     throw new DekError(`ref "${source.name}" is not added`, {
       path: project.configPath,
-      hint: `run \`dekc ref ${arg}\``,
+      hint:
+        source.kind === "file"
+          ? "add it from the pack you were sent: `dekc ref <file>.tgz`"
+          : `run \`dekc ref ${arg}\``,
     });
   }
-  if (source.rev !== undefined && source.rev !== pinned) {
+  // What adds the ref again: a pack's ref from its file, any other from its name.
+  const again =
+    source.kind === "file"
+      ? `dekc ref ${packFile(source.deck)}`
+      : `dekc ref ${source.name}@${pinned}`;
+  if (source.kind === "github" && source.rev !== undefined && source.rev !== pinned) {
     throw new DekError(`"${arg}" is not the pinned version, ${pinned.slice(0, 7)}`, {
       path: project.configPath,
       hint: `run \`dekc ref ${arg}\` to pin that version, or drop @${source.rev}`,
@@ -285,7 +294,7 @@ function resolveRef(cwd: string, arg: string): ReadableDeck & { ref: RefInfo } {
   if (!fetched) {
     throw new DekError(`ref "${source.name}" is not fetched`, {
       path: dir,
-      hint: `run \`dekc ref ${source.name}@${pinned}\``,
+      hint: `run \`${again}\``,
     });
   }
   const snapshot = resolveProject(dir);
@@ -297,7 +306,7 @@ function resolveRef(cwd: string, arg: string): ReadableDeck & { ref: RefInfo } {
     }
     throw new DekError(`ref "${source.name}" has no deck "${source.deck}"`, {
       path: dir,
-      hint: `run \`dekc ref ${source.name}@${pinned}\` to fetch it again`,
+      hint: `run \`${again}\` to fetch it again`,
     });
   }
   return {

package/src/cli/text.ts

@@ -1,6 +1,7 @@
 // How each command's result reads as text; commands.ts says which command prints which.
 // The pieces the dev server's log shares, such as diagnostics and tables, are in format.ts.
 import type { Diagnostic, SkippedCheck } from "../core/diagnostic.ts";
+import { packFile, parseRefSource } from "../core/ref-name.ts";
 import { formatClock } from "../core/timing.ts";
 import type { AnnotationsCliResult } from "./annotations.ts";
 import type { BuildCliResult } from "./build.ts";
@@ -13,6 +14,7 @@ import type { LsDeckResult, LsListResult } from "./ls.ts";
 import type { MarksCliResult } from "./marks.ts";
 import type { MvResult } from "./mv.ts";
 import type { NewResult } from "./new.ts";
+import type { PackCliResult } from "./pack.ts";
 import type { PdfCliResult } from "./pdf.ts";
 import type { RefCliResult } from "./ref.ts";
 import type { ShotCliResult } from "./shot.ts";
@@ -130,7 +132,8 @@ export function formatInit(data: InitResult): string {
 /** The deck, and any of dek's own files it brought up to date: the rest is the deck's, and new. */
 export function formatNew(data: NewResult): string {
   const updated = data.updated.map((path) => `  ${path} (updated)`);
-  return withNext([`created deck ${data.name}`, ...updated].join("\n"), data.next);
+  const warnings = data.warnings.map((warning) => `warning: ${warning}`);
+  return withNext([`created deck ${data.name}`, ...updated, ...warnings].join("\n"), data.next);
 }
 
 export function formatMv(data: MvResult): string {
@@ -227,6 +230,10 @@ export function formatPdf(data: PdfCliResult): string {
   return data.outs.map((path) => `wrote ${path}`).join("\n");
 }
 
+export function formatPack(data: PackCliResult): string {
+  return [formatPdf(data), ...data.warnings.map((warning) => `warning: ${warning}`)].join("\n");
+}
+
 export function formatLs(data: LsListResult | LsDeckResult): string {
   switch (data.kind) {
     case "list": {
@@ -409,6 +416,14 @@ export function formatShow(data: ShowResult): string {
     .join("\n\n");
 }
 
+/** What a read does for a ref whose snapshot is not there: fetch it, or unpack its pack. */
+function notFetched(name: string): string {
+  const source = parseRefSource(name);
+  return source.kind === "file"
+    ? `(not unpacked; a read unpacks ${packFile(source.deck)})`
+    : "(not fetched; a read fetches it)";
+}
+
 export function formatRef(data: RefCliResult): string {
   const short = (rev: string) => rev.slice(0, 7);
   switch (data.action) {
@@ -421,6 +436,7 @@ export function formatRef(data: RefCliResult): string {
       return [
         head,
         ...data.warnings.map((warning) => `warning: ${warning}`),
+        ...(data.pack ? [`commit ${data.pack}: a clone unpacks the ref from it`] : []),
         `read it with \`dekc ls ${data.name}\` and \`dekc show ${data.name} <slug>\``,
       ].join("\n");
     }
@@ -433,7 +449,7 @@ export function formatRef(data: RefCliResult): string {
         data.refs.map((ref) => [
           ref.name,
           short(ref.rev),
-          ref.fetched ? (ref.title ?? "") : "(not fetched; a read fetches it)",
+          ref.fetched ? (ref.title ?? "") : notFetched(ref.name),
           ref.slides === undefined ? "" : String(ref.slides),
         ]),
         ["left", "left", "left", "right"],