konpeki 0.1.0

package/design/review/color-theme.md

@@ -0,0 +1,44 @@
+# Color / theme review
+
+Owns palette use across the deck. Apply existing
+[theme guidance](../../AUTHORING.md#taste-and-creative-freedom) and
+[color roles](../palettes/README.md); this category adds no new style rules.
+
+- Check palette roles, background and visual emphasis against the brief and
+  selected mode. Both modes use the original white-background/main-accent
+  fallback unless the user supplies another direction. Dynamic permits local
+  emphasis fills, not an automatic dark or colored canvas.
+- Check text/mark contrast on actual surfaces at viewing size. Confirm category
+  and status meanings stay consistent and have cues beyond color alone.
+
+Leave font rendering to typography and container structure to visuals.
+Use the shared [review process](../visual-review.md#independent-review).
+
+## Measure a declared solid pair
+
+Use [contrastRatio](../../lib/contrast.ts) for opaque six-digit sRGB hex colors.
+From the kit directory, this checks one declared normal-text pair:
+
+```sh
+node --input-type=module <<'JS'
+import { contrastRatio } from './lib/contrast.ts';
+const foreground = '#505B68', background = '#FFFFFF';
+const ratio = contrastRatio(foreground, background);
+console.log({ foreground, background, ratio, minimum: 4.5 });
+if (ratio < 4.5) process.exitCode = 1;
+JS
+```
+
+Use actual palette roles or rendered values for the pair under review. Record
+the page/element, pair, ratio and applicable threshold. Compare the unrounded
+ratio: rounding 4.478 to 4.5 does not make it pass. Normal text needs 4.5:1;
+large text can use 3:1 only when it qualifies at the delivered size (at least
+24 CSS px regular or about 18.67 CSS px bold). A 32-unit SVG label scaled to
+half size is not 32 CSS px. Contrast does not establish comfortable readability.
+
+This helper does not discover backgrounds, classify text, composite opacity or
+inspect images, gradients and overlapping shapes. Confirm the solid pair really
+applies in the render. For other surfaces, measure the actual composite with an
+appropriate tool and inspect the result; otherwise report contrast as Not verified.
+Never report an unmeasured ratio. The existing theme browser check's containing-
+rectangle assumption remains specimen-specific, not a general background solver.

package/design/review/layout.md

@@ -0,0 +1,16 @@
+# Layout review
+
+Owns composition and spatial relationships. Inspect the rendered deck for
+reading order, grouping and balance. Leave glyph readability to typography,
+diagram meaning and container structure to visuals, and factual claims to text review.
+
+| Check | Guidance |
+| --- | --- |
+| Content balance | Recompose when one column runs far below its neighbor and leaves a stranded empty area. Equal heights are unnecessary. |
+| Heading attachment | Give the heading more separation from the preceding section than from its own content. Respect visible group boundaries. |
+| Evidence-led emphasis | Question the giant-number, small-label, supporting-stats formula. Use it when the metric explains the point, with scope and evidence intact. |
+| Meaningful grouping | Repeated icon–heading–body cards can flatten different ideas into equal weight. Group and prioritize according to meaning. |
+| Paired-row alignment | Align short headings with the first line of their descriptions, not the vertical center of multiline copy. Check visible text alignment as well as element bounds. |
+| Spacing hierarchy | Avoid identical gaps between unrelated sections and within closely related content. A consistent spacing scale is still useful. |
+
+Use the shared [review process](../visual-review.md#independent-review).

package/design/review/text.md

@@ -0,0 +1,18 @@
+# Text review
+
+Owns meaning and wording. Use the brief and sources to verify claims and caveats;
+apply the [writing tone](../../AUTHORING.md#writing-tone). Leave font size and
+visual placement to typography/layout review.
+
+| Check | Guidance |
+| --- | --- |
+| Headline first | Inspect the rendered reading order against the authoring policy. For every eyebrow, brand label and numbered section heading, name the information lost if it were removed. Remove it when that information is already supplied by the headline, nearby content or page navigation, unless explicitly requested. Preserve essential context and required attribution. |
+| Information economy | Avoid restating one message in a card’s headline, badge and note. Repeated values in tables or parallel items can be necessary. |
+| Page purpose | State the audience question answered by the page. Can a reader identify the current state, the decision or mechanism, and its consequence without narration? Replace abstract choice labels and ambiguous pronouns with concrete outcomes and named actors. |
+| Metadata versus evidence | Remove recurring deck metadata unless requested or required. Keep page-specific citations, units, synthetic-data disclosures and material caveats with the evidence; do not remove those as footer clutter. |
+| Relevant limitations | Attach requirements and limits to the mechanism or claim they constrain. Do not give unrelated caveats equal weight on a next-action page or hide essential limits in notes merely to reduce density. |
+| Sentence rhythm | Check for a repeated dash-heavy cadence across the copy. Keep occasional dashes that improve reading. |
+| Concrete claims | Name the capability or supported outcome. Remove claims that could describe any product. |
+| Direct explanation | Remove manufactured rebuttals such as “Not a feature. A platform.” and “not X, but Y.” Explain genuine distinctions directly. |
+
+Use the shared [review process](../visual-review.md#independent-review).

package/design/review/typography.md

@@ -0,0 +1,15 @@
+# Typography review
+
+Owns text rendering and reading comfort. Inspect full/half-size renders for
+legibility, hierarchy, wrapping and clipping; verify actual fonts and weights
+against the chosen [theme](../themes/README.md). Leave wording to text review
+and section placement to layout review.
+
+| Check | Guidance |
+| --- | --- |
+| Font category | Both modes use sans-serif unless the brief directs otherwise. Dynamic may vary typographic emphasis without changing the font category. Verify language coverage, loaded weights and readability in both modes. |
+| Useful numbering | Remove repeated micro-indices beside headings when they add no ordering information. Keep useful step and page numbers readable. |
+| Subheading distinction | Apply the mode table: default requires typographic emphasis; dynamic may establish hierarchy through placement, color or grouping. Check the result at review size. |
+| Readable line measure | Keep paragraph lines easy to track into the next line. Judge the actual font and viewing size; avoid imposing a web character limit on every slide label. |
+
+Use the shared [review process](../visual-review.md#independent-review).

package/design/review/visuals.md

@@ -0,0 +1,31 @@
+# Visuals review
+
+Owns diagrams, charts, imagery and containers. Apply the existing
+[accuracy requirements](../../AUTHORING.md#requirements): verify arrow direction,
+label/value associations, chart scales, asset provenance and faithful crops.
+Text review verifies the underlying claims; this review checks their visual encoding.
+Leave page arrangement to layout and color assignments to color/theme.
+
+Apply the [mode table](../../AUTHORING.md#authoring-mode) first. The allowances
+below for emphasis fills, framing, reinforcing arrows and filled heads apply to
+dynamic mode or an explicit user direction; they do not override default mode's
+original restrictions. Geometry and factual checks apply in both modes.
+
+| Check | Guidance |
+| --- | --- |
+| Visual explanation | Would a diagram, image or annotated artifact make the relationships easier to grasp? Do not accept prose-only treatment merely because it is in bounds, or require a diagram when it adds nothing. |
+| Purposeful boundaries | Judge whether surfaces improve grouping, emphasis or reading order in the chosen direction. Remove competing layers, not all layers that could be replaced by whitespace. Keep meaningful object boundaries and actual controls. |
+| Rules and frames | Dividers must stop at the region they separate, not cross shared copy or subsequent sections. Give text clearance from borders and accent rules. Frames and rails may support grouping or emphasis; distinguish intentional treatment from accidental-looking missing edges. |
+| Paragraphs versus rows | Apply the authoring boundary policy: independent text groups can use whitespace; corresponding table or paired rows may benefit from rules. If rules establish the rows, check for a clear ending before notes, usually a bottom rule. Do not require borders merely because text has columns. |
+| Table ending versus page footer | A closing rule belongs to the table it ends. Do not extend it to the page bottom or add a second separator for generic metadata or a standalone page number. |
+| Canvas padding | Check preview and requested export for unintended padding around differently proportioned artwork. Use the intended aspect ratio where supported or compose the surrounding space deliberately; intentional color bands are not a defect. |
+| Emphasis backgrounds | Does the fill help the audience notice, group or navigate the content? Hierarchy, rhythm and emphasis are valid uses alongside state and evidence. Check contrast and avoid competing emphasis; when color encodes meaning, check that labels or symbols agree. |
+| Connector endpoints | Every arrow needs an identifiable source and destination: a node, participant, lane or explicit continuation. Boxes are optional; meaningful attachment is not. Check what each endpoint refers to, not just its coordinates or alignment. Connectors should meet their intended anchors without stray tails or gaps; extend beyond them only to convey meaning. |
+| Connector routing | Optimize for a clear, coherent route, not the fewest bends. Orthogonal corners are welcome when they support reading order, aligned entry/exit points or label placement. Remove needless doglegs, but do not replace useful elbows with awkward diagonal fans or detach a sequence rail from its stages. Place turns deliberately, with clearance from nodes, labels, boundaries and other connectors; avoid near-touches or crossings that imply unintended junctions. |
+| Corresponding bends | For equivalent or mirrored relationships, check that turn positions, offsets and spacing align or mirror consistently. Preserve asymmetry when different endpoints, obstacles or meanings require it; do not add bends merely to force symmetry. |
+| Arrow purpose | Check that arrows make the intended relationship easier to follow without implying unsupported transitions or dependencies. Reinforcing a relationship stated in words is useful when it speeds understanding, not automatically redundant. |
+| Arrowheads | Open and filled heads are valid. Check consistency with the chosen notation, alignment with shafts, and clean joins without spikes, gaps or protruding stems. Inspect at full and review size. |
+
+Inspect the render: DOM nesting alone cannot establish whether a boundary helps,
+and an HTML card detector can miss nested SVG shapes.
+Use the shared [review process](../visual-review.md#independent-review).

package/design/semantic-patterns.md

@@ -0,0 +1,43 @@
+# Choose a visual by meaning
+
+Start with the audience's question, not a favorite layout. These are choices,
+not templates. Choose the primary medium from the source, audience and brief;
+plain text or a large image may be enough. Authoring mode changes visual rules, not
+the truth of the relationships. More detail requires more supported explanation,
+not more nodes or arrows by default.
+
+## Pick the relationship
+
+| Question | Pattern | Keep clear |
+| --- | --- | --- |
+| What happens next? | Process / sequence | Input, steps, output and blockers. Label branches and return paths; pending is not approved. |
+| Which option fits? | Comparison / decision | Same criteria, units and scope. Explain the recommendation without hiding drawbacks or inventing scores. |
+| What belongs to what? | Hierarchy / containment | Consistent parent–child meaning. Use a map when shared ownership or cross-links matter. |
+| What connects? | System map | Named entities, meaningful boundaries and labeled connections. Use a sequence when event order is the story. |
+| What should I notice? | Annotated detail | Enough context to locate the detail, large evidence and nearby labels. Identify crops and mockups; don't invent specifications. |
+
+Choose theme and composition to suit the relationship. Any pattern can be
+restrained or expressive; decorative shapes must not imply data.
+
+## Infer the form; preserve the meaning
+
+People do not need to name a diagram or chart type. In Auto, infer a suitable form
+from the goal, audience, supplied relationships and data. An explicitly selected form is binding:
+preserve it and ask before switching, including to another component kind. Never
+silently reset explicit selection to Auto. Honor notation requested in the intent
+or brief even in Auto. When ambiguity changes the explanation, ask what should be emphasized rather than
+asking the person to choose from a taxonomy.
+
+Keep specialized semantics when they matter: message order in a sequence,
+guarded transitions in a state machine, enclosure for containment, and honest
+scales for quantities. Use editable vectors when a standard draft cannot express
+them. In Auto, update the returned diagram type or chart template to match the chosen form
+without changing its selection mode.
+
+Diagram Design and Archify are references, not product specifications. Borrow
+useful techniques with attribution; do not pursue their catalog coverage or
+force domain recipes into first-class types. Evaluate the result against the
+explanation goal, factual fidelity and editability.
+
+Render and inspect: is the relationship clear without narration? Are facts,
+arrows and labels correct and readable? No aesthetic score or required layout.

package/design/themes/README.md

@@ -0,0 +1,22 @@
+# Themes
+
+Themes combine font roles and a referenced color palette, not a slide layout.
+
+Use [authoring guidance](../../AUTHORING.md#taste-and-creative-freedom) for theme
+selection, font defaults and deck-wide consistency.
+
+```ts
+import { getTheme } from './design/themes/index.ts';
+const theme = getTheme('Plex', 'paper');
+// theme.body, theme.headline, theme.typography, theme.palette
+```
+
+Eight light/dark themes: Plex, Precision, Editorial, Blue–cyan, Orange–coral,
+Yellow, Green and Graphite. Precision uses Noto Sans; Editorial uses Plex Serif
+headlines with Plex Sans body; the others use Plex Sans. Font loading remains
+the author's responsibility; load the required Fontsource Latin weights before
+measuring or rendering text.
+
+Mineral and Botanical are light-only palette candidates in
+[palettes/candidates.ts](../palettes/candidates.ts).
+A theme does not impose geometry, density or supporting-text sizes.

package/design/themes/index.ts

@@ -0,0 +1,13 @@
+import { typography } from '../../lib/taste.ts';
+import { paletteNames, resolvePalette, type PaletteName, type PaletteMode } from '../palettes/index.ts';
+
+export const themeNames = paletteNames;
+export type ThemeName = PaletteName;
+export type ThemeMode = PaletteMode;
+
+// Themes combine typography with a palette; they do not choose a composition.
+export function getTheme(name: ThemeName, mode: ThemeMode) {
+  const body = name === 'Precision' ? '"Noto Sans", sans-serif' : typography.family;
+  const headline = name === 'Editorial' ? '"IBM Plex Serif", serif' : body;
+  return { name, body, headline, typography: { ...typography, family: body }, palette: resolvePalette(name, mode) };
+}

package/design/visual-languages/technical-product.md

@@ -0,0 +1,17 @@
+# Technical product
+
+Use for product explanations, processes and comparisons where a concrete visual
+can carry the argument. This is art direction, not a palette or a fixed template.
+
+- Give the product/interface/output enough space to explain the claim.
+- Apply the selected mode's framing and emphasis rules; do not flatten
+  unrelated content into equally prominent boxes.
+- Connect a process to its tangible output. Keep labels near their connectors.
+- Make selection/recommendation distinct without obscuring alternatives.
+- Keep diagrams and annotations readable at the intended viewing size. Shared
+  card headers round outer top corners only, not the internal bottom seam.
+- Avoid importing website density, tiny gray labels, ubiquitous registration
+  marks, or scroll effects into slides.
+
+Works with Blue–cyan light or Graphite dark; these are examples, not limits.
+Reference: [user-supplied website video](https://video.twimg.com/amplify_video/2097350430993072128/vid/avc1/2306x2160/IgjnX7Duukk4W54G.mp4).

package/design/visual-review.md

@@ -0,0 +1,88 @@
+# Focused visual review
+
+Choose the relevant categories for the work. Each owns its checks; shared
+requirements remain in [AUTHORING](../AUTHORING.md). Apply judgment to the
+content; no automatic bans or aesthetic score.
+
+All categories apply the selected [authoring mode](../AUTHORING.md#authoring-mode)
+and explicit brief. Default uses the original visual restrictions; dynamic
+relaxes only the rules named in the mode table. That table takes precedence over
+general suggestions below and in category guides. Do not impose default-only
+restrictions on dynamic work or require dynamic work to add effects. Judge
+explanation structure and depth against the source, audience and brief.
+Correctness, readability and source fidelity remain non-negotiable in both modes.
+Report a mode mismatch separately from a factual/access defect or taste preference.
+
+| Category | Scope |
+| --- | --- |
+| [Text](review/text.md) | Meaning, claims, repetition and writing tone |
+| [Typography](review/typography.md) | Font rendering, text hierarchy and reading comfort |
+| [Layout](review/layout.md) | Composition, grouping, spacing and comparisons |
+| [Color / theme](review/color-theme.md) | Deck-wide direction, contrast and semantic color roles |
+| [Visuals](review/visuals.md) | Diagrams, charts, imagery and meaningful boundaries |
+
+## Independent review
+
+For a small change, review directly. When useful and subagents are available,
+assign independent categories concurrently. Give each reviewer the same brief,
+chosen direction, source and full/half-size renders, plus its category file.
+Reviewers inspect their scope without editing files or reading each other's findings.
+
+Return only meaningful findings: **priority · page/element · evidence · reader
+impact · suggested fix**. Distinguish observed defects from design suggestions;
+list checks not performed as **Not verified**, not as defects or passes.
+An empty finding list is valid.
+The coordinator deduplicates cross-category issues, resolves conflicting fixes
+against the brief, and checks narrative flow and deck coherence. Report a shared
+root cause once, naming affected pages. Apply fixes in one editing pass,
+then re-render affected pages and repeat relevant checks.
+
+## Repair order
+
+1. **Accuracy:** factual errors, misleading scales, missing qualifications and
+   incorrect relationships.
+2. **Access to content:** unreadable, missing or clipped essential content,
+   color-only meaning and inaccessible interactions when present.
+3. **Understanding:** grouping, reading order, hierarchy and deck coherence.
+4. **Polish:** optical alignment, decorative details and surface consistency.
+
+Judge whether the treatment helps the audience, not whether it could be removed.
+A repair may add a diagram, color field or annotation, or remove competing
+material. Reuse existing primitives where useful; never delete required evidence to improve fit.
+Repair upstream causes first: a cramped region may need recomposition rather
+than separate font-size, line-break and padding changes.
+
+### Repair examples
+
+These are diagnostic examples, not measured findings or mandatory layouts.
+Render the repair with real content to judge whether it helps.
+
+| Before | After | Why |
+| --- | --- | --- |
+| A heading sits equally far from the preceding section and its own paragraph. | Move it nearer its paragraph and increase separation from the preceding section. | Proximity makes ownership clear without another box. |
+| A wide diagram leaves its evidence and caveat in tiny side text. | Give the evidence a larger region or split the page while retaining the qualification. | Essential context becomes readable without shrinking the diagram's labels. |
+| A large value dominates a faint unit and denominator. | Keep unit and denominator adjacent and readable; reduce the value's dominance if needed. | The reader can interpret the number rather than just notice it. |
+| Every sentence sits in an equally prominent nested panel. | Reduce competing layers; retain surfaces that support grouping, emphasis or the chosen direction. | The audience can distinguish the main point from supporting material. |
+| A prose list makes readers reconstruct a request journey. | Draw the named participants and labeled connections, retaining useful explanatory copy. | Relationships become easier to follow even though words already describe them. |
+
+## Accessibility and delivery
+
+Apply checks to the requested format, at its actual viewing size. These are
+delivery checks, not a claim of full accessibility conformance.
+The author (or coordinator when review is delegated) owns this checklist and
+records evidence or **Not verified** for every applicable check.
+
+- Check captions, sources, units and caveats as carefully as the headline.
+  Keep category and state meanings available through labels, shapes or patterns,
+  not color alone. Measure contrast on actual surfaces; see [color review](review/color-theme.md).
+- For browser slides, provide meaningful accessible descriptions or a text
+  equivalent for visual content. Check reading order and that chart alternatives
+  convey the conclusion and relevant values, not merely “chart.” Confirm the
+  content is exposed in the accessibility tree; source markup alone is insufficient.
+- When controls or motion are included, exercise keyboard navigation, visible
+  focus and accessible control names. Check the reduced-motion path and ensure
+  state changes remain understandable without animation. Keep runtime fixes
+  upstream rather than building a second navigation or export system.
+- Inspect each requested export for text, fonts, reading order and alternatives
+  as applicable. Browser/PNG success does not establish accessible PDF/PPTX or
+  cross-application fidelity. Report unsupported or untested delivery properties.

package/docs/development.md

@@ -0,0 +1,140 @@
+# Development
+
+Clone `https://github.com/vcfgdev/konpeki.git` with the required repository access.
+Use [mise](https://mise.jdx.dev/getting-started.html) to install the Node.js and
+pnpm versions pinned in `mise.toml`. On macOS, install mise with `brew install mise`.
+From the repository root:
+
+```sh
+mise trust
+mise install
+mise exec -- pnpm install --frozen-lockfile
+```
+
+Mise manages the toolchain; pnpm manages dependencies through `pnpm-lock.yaml`.
+Run the commands below from that repository root with an activated mise shell,
+or prefix them with `mise exec --` (for example, `mise exec -- pnpm test`).
+No global Node.js or pnpm installation is required. npm for packing and publishing
+comes with the pinned Node.js; use `mise exec -- npm pack` to select it explicitly.
+
+Development and regression checks require a repository checkout, not an npm
+tarball, which excludes tests and review scripts.
+
+## Development server and demo hosting
+
+```sh
+pnpm dev
+```
+
+For a production preview, run `pnpm build` then `pnpm preview`. The build produces
+a static site in `dist` for a root or subdirectory. Use
+`?example=introducing-konpeki` or `?example=custom-visual` to open a bundled editable
+example. Example links do not autosave; open a composition in a file-backed
+session to preserve edits.
+
+Hosting shares bundled examples, not private drafts, arbitrary documents or an
+AI service. No deployment is automatic. In a remote environment, expose the
+server through its authenticated preview mechanism; a local address is not a
+shareable URL.
+
+## Implementation reference
+
+- `src/` contains the shared canvas application for editing and presentation.
+  The [versioned composition contract](../composition/README.md) preserves
+  content, relationships and visual intent across human and agent revisions.
+- `bin/` contains the file-session CLI and its revision-checked persistence.
+- [AUTHORING.md](../AUTHORING.md) owns design defaults, factual fidelity and review.
+  [Design resources](../design/README.md) provide palettes, themes and semantic
+  patterns; these are choices, not mandatory layouts.
+- `lib/text.tsx` supplies measured `Text` and `Paragraphs` with string or rich-text
+  runs. Overset content is flagged, not automatically shrunk or hidden. Await
+  `fontsReady` from `lib/typeface.ts` before measuring.
+- `lib/slide.tsx` supplies specimen `Panel`, `Relationship` and 1920×1080 `Sheet`
+  components. `Panel` shares one heading/body size; `Relationship` is a short
+  directional glyph. Convert their SVG output to composition vectors for the canvas.
+- `lib/layouts.ts` supplies fixed-gutter regions, not a content-fitting solver.
+- Retained React chart references use Nivo `Bar`, `Line` and `Sankey` with
+  `chartDefaults(palette)` from `lib/charts.ts` spread before chart-specific props.
+  Keep data, dimensions, scales and semantic colors in the deck. Use explicit
+  label colors and `linkBlendMode="normal"` for Sankey.
+
+### React/SVG drawing references
+
+The retained `slides/*/index.tsx` files are presentation-runtime-independent
+drawing references. They are checked as source but are not discovered as routes
+or executed by a second presentation runtime. New decks use composition JSON;
+a trusted build may render React to SVG, then convert supported elements into
+the owning component's editable vector payload.
+
+To migrate the retained architecture reference into the shared canvas:
+
+```sh
+pnpm example:migrate-page slides/architecture/index.tsx all /tmp/architecture-composition.json
+```
+
+Drag the resulting JSON onto the canvas, edit its vectors, and use **Present**.
+Replace `all` with a zero-based page index for one page. This command executes
+trusted local React source; never use it on untrusted JSX. It rejects unsupported
+SVG elements rather than silently flattening them. Review converted typography
+and geometry in the browser; conversion is not a fidelity guarantee.
+The bundled `?example=react-page-migration` preview uses the same format.
+Example previews do not autosave; use a file-backed session to save edits.
+
+## Package contents
+
+`package.json` explicitly allowlists the npm payload: the source-based Vite
+runtime and file-session CLI, authoring guidance and design resources, and named
+curated examples with editable source and prompts. New example directories are
+not included automatically. Gallery screenshots, tests, research fixtures,
+browser review scripts, original branding assets, lockfiles and UI build output
+stay in the repository.
+
+`npm pack` builds the JavaScript CLI in `runtime/` automatically because Node
+cannot load its TypeScript source from inside `node_modules`. That generated
+CLI is included in the package.
+
+Run `pnpm check:package` before preparing a release. It checks npm's file selection,
+required resources, excluded development files and relative imports. For an
+installation smoke test, use `npm pack --pack-destination <temporary-dir>`, install
+the tarball in an empty project, then run its `konpeki validate` and `konpeki preview`
+commands against a composition outside the installed package. Do not publish
+until that isolated preview works. Publish the tested tarball rather than
+rebuilding during publication. Packing locally does not publish anything.
+
+## Verification
+
+```sh
+pnpm check
+pnpm test
+pnpm build
+pnpm check:package
+```
+
+With the dev server running and `agent-browser` installed:
+
+```sh
+node scripts/check-canvas.mjs http://localhost:4318 .amp/in/artifacts
+node scripts/check-pages.mjs http://localhost:4318 .amp/in/artifacts/pages
+```
+
+These checks exercise all five component kinds, empty slides, JSON round trips,
+vector editing/history and fitted line dragging. They capture editor and
+presentation states at two sizes; inspect the images because assertions alone
+do not establish visual correctness.
+
+Documentation changes need link and instruction checks. Deck changes need
+typecheck, build, relevant fixture checks and actual visual inspection. Shared
+component, theme or dependency changes also need the full test suite and
+representative affected decks. A build can report a large-framework-chunk advisory.
+
+Render affected pages at presentation and review sizes after fonts load. Inspect
+text, clipping, relationships, contrast and cross-page consistency. Repair issues
+and inspect fresh captures. Keep browser checks scoped to factual and layout
+contracts, not universal taste. Record untested outputs and limitations with
+the example; screenshots do not prove PDF/PPTX or cross-application fidelity.
+
+When adding examples, preserve the exact creative requests, editable source,
+source facts and reviewed images as described in [AUTHORING.md](../AUTHORING.md).
+Examples demonstrate capabilities; there is no separate benchmark suite or
+aesthetic score. Check font language subsets and license notices when
+redistributing assets; dependencies retain their own licenses.

package/docs/workflow.md

@@ -0,0 +1,61 @@
+# Canvas workflow
+
+Start with the [quickstart](../README.md#start-in-your-coding-agent) and give your
+coding agent a brief in its prompt field. Keep the skill with the project:
+copying `SKILL.md` alone does not install Konpeki. Skill discovery varies by
+agent; there is no universal `/konpeki` command.
+
+## Documents and exports
+
+New documents live in `slides/<name>/composition.json`, with `PROMPT.md`, source
+notes and reviewed images alongside. Keep the editable composition under version
+control. The canvas is the source of truth for editing and presentation; download
+its JSON for handoff and drag returned JSON onto the canvas to continue.
+
+One page is a complete creation. Presets cover Presentation (1920×1080), Square
+post (1080×1080), Portrait post (1080×1350), Link preview / OG (1200×630), and
+Article header (1600×600). The document contract supports 256–4096 pixels per side.
+Pages in one document may use different sizes. Changing size never stretches
+content and is refused when existing components would fall outside the page.
+Recompose for a new aspect ratio instead of stretching or cropping.
+
+**Export PNG** saves the active page at its declared dimensions without editor
+controls. JSON remains the editable source; PNG is an image. Fresh documents and
+added pages are empty. **Present** uses the same renderer for any page sequence.
+
+Standard Chart, Diagram and Table illustrations are structural drafts. Finished
+artwork can remain owned by its semantic component as editable vector elements.
+Retained React/SVG examples are drawing references, not another deck runtime.
+
+## File-backed editing with an agent
+
+The CLI interface is `konpeki <command>`. After local installation, use
+`npm exec --no -- konpeki <command>` from your workspace. In a repository checkout,
+use the development shim `pnpm konpeki <command>` instead:
+
+```sh
+npm exec --no -- konpeki validate slides/my-visual/composition.json
+npm exec --no -- konpeki preview slides/my-visual/composition.json
+```
+
+`preview` prints a capability-bearing local URL. Open that exact URL. Valid
+browser edits are saved atomically to the composition file; a revision hash
+prevents overwriting concurrent external changes. When an agent updates the same
+file, the canvas loads the valid revision and keeps the previous document in Undo.
+
+An agent waiting for a person's revision request runs:
+
+```sh
+npm exec --no -- konpeki wait slides/my-visual/composition.json
+```
+
+In the file-backed canvas, **Build it** saves the composition and submits the
+exact revision, active page and optional selected component. `wait` prints that
+machine-readable request and exits. It does not launch or wake an agent itself.
+The listening agent must reread the named composition, preserve unrelated human
+edits, validate, render and inspect its revision before returning. Browser-local
+drafts and hosted examples do not expose **Build it** because no local agent owns
+their files.
+
+Browser screenshots do not establish PDF/PPTX editability, font embedding or
+cross-application fidelity. Inspect every requested export separately.

package/index.html

@@ -0,0 +1,17 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta name="theme-color" content="#ffffff" />
+    <meta
+      name="description"
+      content="An editable canvas for agent-made visuals. Create a single explanation or a whole presentation, then revise it together."
+    />
+    <title>Konpeki</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/lib/assets.d.ts

@@ -0,0 +1,8 @@
+declare module '*?url' {
+  const url: string;
+  export default url;
+}
+declare module '*?raw' {
+  const text: string;
+  export default text;
+}

package/lib/charts.ts

@@ -0,0 +1,18 @@
+import { typography, type Palette } from './taste.ts';
+
+// Shared presentation defaults for Nivo SVG components, not a chart wrapper.
+// Decks still own data, dimensions, scales, labels and semantic color assignments.
+export function chartDefaults(p: Palette) {
+  return {
+    animate: false,
+    isInteractive: false,
+    renderWrapper: false,
+    colors: [p.accent, p.emphasis],
+    theme: {
+      text: { fontFamily: typography.family, fontSize: typography.caption, fill: p.fg },
+      axis: { ticks: { text: { fill: p.fg, fontSize: typography.caption } }, domain: { line: { stroke: p.line } } },
+      grid: { line: { stroke: p.line, strokeWidth: 1 } },
+      labels: { text: { fontSize: typography.caption, fill: p.fg } },
+    },
+  };
+}

package/lib/contrast.ts

@@ -0,0 +1,16 @@
+// WCAG relative luminance for opaque, six-digit sRGB hex colors only.
+// Callers must establish the actual rendered pair; this does not inspect a DOM.
+export function contrastRatio(foreground: string, background: string): number {
+  const luminance = (color: string) => {
+    if (!/^#[0-9a-f]{6}$/i.test(color)) {
+      throw new Error('Contrast requires opaque six-digit sRGB hex colors (#RRGGBB).');
+    }
+    const channels = [1, 3, 5].map(offset => {
+      const value = Number.parseInt(color.slice(offset, offset + 2), 16) / 255;
+      return value <= 0.04045 ? value / 12.92 : ((value + 0.055) / 1.055) ** 2.4;
+    });
+    return 0.2126 * channels[0] + 0.7152 * channels[1] + 0.0722 * channels[2];
+  };
+  const fg = luminance(foreground), bg = luminance(background);
+  return (Math.max(fg, bg) + 0.05) / (Math.min(fg, bg) + 0.05);
+}

package/lib/layouts.ts

@@ -0,0 +1,50 @@
+export type Region = { x: number; y: number; width: number; height: number };
+export type RelationshipSlot = { x: number; y: number; axis: 'horizontal' | 'vertical' };
+export const layoutKinds = ['two-columns', 'main-aside', 'three-columns', 'four-grid', 'one-left', 'one-right', 'one-top', 'one-bottom'] as const;
+export type LayoutKind = typeof layoutKinds[number];
+export const contentRegion: Region = { x: 112, y: 404, width: 1696, height: 520 };
+
+function split(area: Region, axis: 'horizontal' | 'vertical', weights: number[], gap: number): Region[] {
+  const length = axis === 'horizontal' ? area.width : area.height;
+  const available = length - gap * (weights.length - 1);
+  const total = weights.reduce((a, b) => a + b, 0);
+  let offset = 0;
+  return weights.map(weight => {
+    const size = available * weight / total;
+    const region = axis === 'horizontal'
+      ? { ...area, x: area.x + offset, width: size }
+      : { ...area, y: area.y + offset, height: size };
+    offset += size + gap;
+    return region;
+  });
+}
+
+function between(a: Region, b: Region, axis: RelationshipSlot['axis']): RelationshipSlot {
+  return axis === 'horizontal'
+    ? { x: (a.x + a.width + b.x) / 2, y: a.y + a.height / 2, axis }
+    : { x: a.x + a.width / 2, y: (a.y + a.height + b.y) / 2, axis };
+}
+
+// Regions and relationship gutters, not an automatic layout/diagram solver.
+// A slot is available space; the author decides whether an arrow belongs there.
+export function arrange(kind: LayoutKind, area: Region = contentRegion, gap = 80): { panels: Region[]; slots: RelationshipSlot[] } {
+  if (kind === 'two-columns' || kind === 'main-aside' || kind === 'three-columns') {
+    const weights = kind === 'main-aside' ? [2, 1] : kind === 'three-columns' ? [1, 1, 1] : [1, 1];
+    const panels = split(area, 'horizontal', weights, gap);
+    return { panels, slots: panels.slice(1).map((panel, i) => between(panels[i], panel, 'horizontal')) };
+  }
+  if (kind === 'four-grid') {
+    const rows = split(area, 'vertical', [1, 1], gap);
+    const panels = rows.flatMap(row => split(row, 'horizontal', [1, 1], gap));
+    return { panels, slots: [between(panels[0], panels[1], 'horizontal'), between(panels[2], panels[3], 'horizontal'), between(panels[0], panels[2], 'vertical'), between(panels[1], panels[3], 'vertical')] };
+  }
+  const axis = kind === 'one-top' || kind === 'one-bottom' ? 'vertical' : 'horizontal';
+  const halves = split(area, axis, [1, 1], gap);
+  const reversed = kind === 'one-right' || kind === 'one-bottom';
+  const single = halves[reversed ? 1 : 0], group = halves[reversed ? 0 : 1];
+  // Single panel is always index 0; the three siblings follow in reading order.
+  return {
+    panels: [single, ...split(group, axis === 'horizontal' ? 'vertical' : 'horizontal', [1, 1, 1], 32)],
+    slots: [between(halves[0], halves[1], axis)],
+  };
+}