Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 16 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,22 @@ does not currently publish versioned releases.

## Unreleased

### Renderer upgrade

- Upgrade `@topo/diagram-core` to the complete pristine Archify 3.0.0 release
ZIP at `9286c3b9c2cef359e98586b420d769d87bcb163f`, with all 104 runtime files
verified, metadata outside the vendor tree, and the previous integrity
baseline preserved. Builds and runtime remain download-free.
- Supply v3 output-path metadata at the adapter boundary without rewriting
authored stories. Preserve compatible Lifecycle v1 inputs and the 12px
effective-text requirement through final-font sizing and native route gaps.
- Preserve native v3 raster figure exports with their title and padded frame,
while verifying that inner diagram geometry remains uniformly scaled.
Lifecycle omits empty bands and visibly marks terminal states.
- Retain upstream MIT, third-party and font notices unchanged; no vendor patch,
npm renderer dependency, license-policy expansion or upstream-suite completion
is implied. Refs #41.

### Added

- Add default source-grounded Repository exploration through pinned Archify:
Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ everything a human adds is recorded as such.

> **Status: Local preview.** The scan-to-site workflow, deterministic reports,
> source-grounded stories, static analysis modules, optional AI commentary, and
> pinned Archify rendering are implemented. Topo is the storybook for
> pinned Archify 3.0.0 rendering are implemented. Topo is the storybook for
> architects: the generated shell inventories every diagram while preserving
> real Archify viewers. This is not yet a published npm CLI.

Expand Down
15 changes: 8 additions & 7 deletions docs/product-spec.md
Original file line number Diff line number Diff line change
Expand Up @@ -78,8 +78,9 @@ scanning and structural validation.
- A renderer can be replaced or added behind the adapter without changing story
documents. Adapter tests check output and failure behavior, not internal call
order. **AC-15**
- The current renderer pin is Archify `2.17.0-dev.1` at exact revision
`d673e8300df60a5c8166abe78787fdc78f6b8000`.
- The current renderer pin is Archify `3.0.0` at exact revision
`9286c3b9c2cef359e98586b420d769d87bcb163f`. The owner selected a pristine
checked-in copy of the official release ZIP, with no build-time download.
- The wrapper owns catalogue navigation, deep links, and restored node focus.
Archify owns diagram geometry, theme, presentation, zoom, evidence details,
and canonical SVG/PNG export. **CON-08, AC-19**
Expand Down Expand Up @@ -136,9 +137,9 @@ for this work. These clauses are requirements, not waivers:
| Original clause | Current state | Required end state |
| --- | --- | --- |
| **AC-10, NFR-02** | The shipped license gate uses scoped handling for embedded font notices. Its literal allowlist does not contain `OFL-1.1`. This is a specification reconciliation gap, not evidence of a license violation or missing notices. | Decide how the original narrow `OFL-1.1` allowlist wording maps to the scoped implementation. Do not silently broaden license policy. |
| **AC-16** | The runtime package integrity-checks the 62 files it ships. | Also preserve and verify the exact pristine upstream inventory of 214 files at `d673e8300df60a5c8166abe78787fdc78f6b8000`. Drift must fail loudly without rewriting the historical baseline. |
| **AC-16** | The owner-approved v3 release ZIP supplies all 104 runtime files, each integrity-checked; the former 62-file runtime manifest remains preserved unchanged. | The approved v3 distribution replaces the old pin/inventory target. Keep the exact pristine runtime and fail loudly on drift. This is not a claim that the former 214-file upstream-source requirement was retroactively delivered. |
| **AC-17** | Topocode smoke and regression tests exercise the integrated renderer. | Run the real upstream test suite that accompanies the pristine pin in Node.js 22/Linux CI. Do not replace it with an empty gate or Topocode-only smoke tests. |
| **AC-18, CON-07** | Required license and notice material is shipped with the runtime subset. | Retain upstream `LICENSE`, `THIRD_PARTY_NOTICES.md`, brand attribution, and trademark disclaimer verbatim. Contribute changes upstream first. If blocked, use an explicit listed patch set over the pristine copy. Each patch records whether it is still needed or has landed upstream. Never make silent in-place edits. |
| **AC-18, CON-07** | The full official v3 runtime and required license/notice material are retained verbatim, with no vendor patches. | Retain upstream `LICENSE`, `THIRD_PARTY_NOTICES.md`, brand attribution, and trademark disclaimer verbatim. Contribute changes upstream first. If blocked, use an explicit listed patch set over the pristine copy. Each patch records whether it is still needed or has landed upstream. Never make silent in-place edits. |

The vendored package is a swappable seam, not a goal to maintain a divergent
fork. If upstream publishes a usable package, `@topo/diagram-core` may become a
Expand Down Expand Up @@ -169,18 +170,18 @@ This table preserves the disposition of every numbered original requirement.
| **FR-06; AC-11** | Partly shipped: bounded catalogue configuration. Broader composition/extensibility and the required manual walkthrough remain unresolved above. |
| **FR-07; AC-12** | Workflow shipped; the required manual agent-authoring walkthrough remains unresolved above. |
| **FR-08; AC-02** | Shipped objective anchor failures; no heuristic staleness gate. |
| **FR-09; AC-04** | Shipped package boundary and exact revision pin. Full-copy obligations remain below. |
| **FR-09; AC-04** | Shipped package boundary and exact revision pin. The approved v3 release runtime is complete; upstream-suite integration remains below. |
| **NFR-01; AC-09** | Shipped notices in generated and bundled output. |
| **NFR-02; AC-10** | Unresolved wording-to-implementation reconciliation in #41. |
| **NFR-03; AC-03** | Same-environment repeat-render equivalence shipped; required cross-machine reproducibility remains unverified above. |
| **NFR-05** | Historical POC sizes remain evidence, not budgets or current performance claims. |
| **NFR-06** | No extra accessibility, security, privacy, reliability, or operability target was agreed. Existing safeguards still apply. |
| **CON-01** | Maintained: building Topocode and a consumer's deployment pipeline are separate systems. |
| **CON-02** | Maintained: exact vendored pin behind `@topo/diagram-core`; full-copy work remains in #41. |
| **CON-02** | Maintained: exact pristine v3 release ZIP behind `@topo/diagram-core`; unresolved upstream-suite/license commitments remain in #41. |
| **CON-03; AC-14** | Shipped CI baseline; **AC-17** remains unresolved in #41. |
| **CON-04; U-3** | Superseded: PR #71 removed the WebGL explorer. #70 supplies the bounded source-grounded Archify replacement in the same shell. |
| **CON-05, CON-06** | Maintained platform and evidence-preservation constraints. |
| **CON-07; AC-16, AC-18** | Unresolved pristine-copy and explicit-patch obligations in #41. |
| **CON-07; AC-16, AC-18** | Approved v3 pristine runtime and verbatim notices shipped; historical baselines retained. Upstream-first and explicit-patch policy remains mandatory. |
| **CON-08; AC-19** | Shipped wrapper-side links and focus restoration. |

Other source clauses remain bounded as follows: dirty-tree behavior must keep
Expand Down
46 changes: 45 additions & 1 deletion docs/renderer.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# Rendering boundary

Topo renders committed diagram stories through the pinned, integrity-checked
Archify runtime in `@topo/diagram-core`. Authored `.topo.json` documents remain
Archify 3.0.0 runtime in `@topo/diagram-core`. Authored `.topo.json` documents remain
renderer-neutral; source anchors resolve before rendering, and failures do not
publish partial output.

Expand All @@ -12,6 +12,50 @@ theme, presentation, zoom, source/evidence details, and canonical SVG/PNG
exports. The shell owns navigation, grouping, filtering, Git-backed sorting,
responsive containment, and deep-link coordination around that iframe.

## Pinned distribution and upgrades

The checked-in `packages/diagram-core/vendor/archify/` directory is the complete,
unmodified 104-file runtime from the official
[v3.0.0 release ZIP](https://github.com/tt-a1i/archify/releases/tag/v3.0.0),
at commit `9286c3b9c2cef359e98586b420d769d87bcb163f`.
`archify-pin.json` records its source and archive SHA-256;
`archify-integrity.json` verifies every path and file. Metadata stays outside
the upstream tree. Build and rendering require no runtime download or npm
package named `archify`.

The prior 2.17.0-dev.1 runtime manifest is preserved unchanged under
`packages/diagram-core/integrity/`. A future upgrade needs its own reviewed
pin and inventory, not an integrity-baseline rewrite to bless local edits.
Keep upstream licenses, font notices, brand attribution and trademark
disclaimers verbatim. Proposed renderer changes go upstream first; any approved
local patch must be separately listed with its upstream status. This pin has
no vendor patches.

The v3 adapter adds portable `meta.output` only to its generated renderer input;
authored Topocode stories retain their identity and schema.
Rendering runs in an owned temporary working directory, so resolving that
generated output field cannot depend on an unrelated `story.html` in the
caller's directory.
Lifecycle remains
on the compatible native v1 geometry: state widths and column clearance account
for final typography, preserving Topocode's 12px effective text requirement.
The v3 viewer's own guided/story-view and ordinary share-card removal does not
remove Topocode's authored-story catalogue or canonical SVG/PNG exports.
Native v3 PNG exports add the viewer's title and canvas frame around the
uniformly scaled canonical diagram. SVG remains the bare canonical geometry;
the test oracle accounts for frame dimensions rather than distorting or
cropping the diagram to preserve the previous whole-image aspect ratio.

Native `deliver` provenance receipts describe the raw native artifact. Topocode
then applies adapter typography/narrative changes and, for repository views,
shared-asset packaging. Those bytes must not be presented as the original
native artifact's hash or as a successful upstream `finalize` result.
Topocode validates its delivered behavior through the existing CLI/browser
regressions. The public release ZIP intentionally omits the upstream test
suite; integrating that suite remains separate work in #41.

## Generated repository views

The default Repository canvas uses bounded generated Architecture views at
`/repository/<view-id>/viewer.html` through the same package boundary. Its
wrapper owns scanner/source evidence and navigation, including explicit dirty,
Expand Down
15 changes: 13 additions & 2 deletions docs/story-preview.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,14 @@ cannot satisfy the renderer's legible minimum still fails explicitly.
Lifecycle state widths are derived from their authored titles, then all states
are placed together within their semantic native lanes so a wide state cannot
silently reuse a neighboring state's column.
The Archify 3.0.0 adapter retains native Lifecycle schema v1; it reserves the
native minimum route gap and sizes states for final 14.5px typography so the
adaptive viewer still meets Topocode's 12px effective on-screen text floor.
Lifecycle uses an explicit Arial/Helvetica sans-serif stack rather than the
host's `system-ui` face, keeping wide-label fitting stable across the supported
macOS and Linux browser environments.
Native v3 Lifecycle output omits empty bands and adds the terminal state's
double border; neither changes authored state or transition membership.

The optional `classification` is `source-grounded` or `capability-demo`;
omission retains the source-grounded behavior. Every source-grounded section
Expand Down Expand Up @@ -80,8 +88,11 @@ renderer failures exit nonzero. Rendering completes in memory before the
generated file is atomically replaced, so renderer failures do not publish a
partial story.

The viewer exports the same canonical authored geometry as SVG or a
resolution-scaled PNG. Local serving permits blob images only for generated
The viewer exports canonical authored geometry as SVG. Native v3 PNG exports
place that same geometry, uniformly scaled, inside a title row and padded
canvas card; the complete PNG therefore has a different aspect ratio than the
bare SVG. No diagram content is cropped to force the old ratio.
Local serving permits blob images only for generated
story viewers so the pinned runtime can rasterize its serialized SVG without
broadening the Content Security Policy for shell pages.

Expand Down
6 changes: 3 additions & 3 deletions packages/cli/src/story-preview.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -269,14 +269,14 @@ describe("story preview", () => {
expect(contents).toContain("Charge the accepted order.");
});

it("renders a committed lifecycle story with native lifecycle bands", async () => {
it("renders populated lifecycle bands without inventing an empty recovery phase", async () => {
const { root, documentPath } = await fixture(familyStory("lifecycle"));

const result = await previewStory(root, documentPath);
const contents = await readFile(result.outputPath, "utf8");

expect(contents).toContain("01 / Checkout");
expect(contents).toContain("02 / Interruptions + recovery");
expect(contents).not.toContain("02 / Interruptions + recovery");
expect(contents).toContain("03 / Outcomes");
});

Expand Down Expand Up @@ -401,7 +401,7 @@ describe("story preview", () => {
const secondContents = await readFile(second.outputPath, "utf8");

expect(secondContents).toBe(firstContents);
expect(first.renderer).toEqual({ name: "archify", pin: "2.17.0-dev.1" });
expect(first.renderer).toEqual({ name: "archify", pin: "3.0.0" });
expect(firstContents).toContain("<svg");
expect(firstContents).toContain("Submit");
});
Expand Down
15 changes: 13 additions & 2 deletions packages/diagram-core/THIRD_PARTY_NOTICES.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,18 @@
# Third-party notices

This package vendors Archify 2.17.0-dev.1 at revision
`d673e8300df60a5c8166abe78787fdc78f6b8000`.
This package vendors the pristine Archify 3.0.0 release ZIP at revision
`9286c3b9c2cef359e98586b420d769d87bcb163f`.

`archify-pin.json` records the official archive URL and SHA-256. All 104
upstream files are unchanged; `archify-integrity.json` checks their exact
inventory and bytes. Topocode's pin metadata remains outside the pristine
vendor tree. The previous runtime manifest is preserved unchanged in
`integrity/archify-2.17.0-dev.1.json`.

Renderer adaptations belong in Topocode's adapter, not the upstream copy.
Contribute required renderer changes upstream first; an explicitly approved
patch must be separately listed with its upstream status. There are no vendor
patches in this distribution. No runtime download occurs during build or use.

The complete upstream license and notices are retained verbatim in:

Expand Down
Loading
Loading