8000 Obelus v1.3: the page and the mark, plus the backlog by kiran-brahma · Pull Request #90 · kiran-brahma/writing-tool · GitHub
[go: up one dir, main page]

Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
20 commits
Select commit Hold shift + click to select a range
7aa2623
Name the navigation-time prune as the shell cache's rollback mechanis…
kiran-brahma Sep 26, 2026
a799085
Say in the metrics panel that a number-and-period opening is one sent…
kiran-brahma Sep 26, 2026
42d9d3f
fix: key the Run cache on a Connection's ceiling, reasoning and heade…
kiran-brahma Sep 26, 2026
f14f942
Report a chunked Audit's true model-call count (#73)
kiran-brahma Sep 26, 2026
a8256f0
fix: a Paragraph inside a list item can be a local Pass's Target (#75)
kiran-brahma Sep 26, 2026
bc3973f
A link href with an unbalanced parenthesis breaks the Markdown round-…
kiran-brahma Sep 26, 2026
e9fa7b3
Bound a stalled Provider call so it cannot hold the mutation lock (#4…
kiran-brahma Sep 26, 2026
f57d158
Colour names with today's colours (#77)
kiran-brahma Sep 26, 2026
0aac552
Move the other screens to colour names, type scale and focus rings (#78)
kiran-brahma Sep 26, 2026
1beb326
Move the Editor surface to colour names, with focus rings (#79)
kiran-brahma Sep 26, 2026
4b8a479
Move the Rail to colour names, with focus rings (#80)
kiran-brahma Sep 26, 2026
b38d527
Dark scheme and the Light | Dark | System choice (#62) (#81)
kiran-brahma Sep 26, 2026
69a131a
Rank the header's destinations and the Callout's verdicts (#68) (#82)
kiran-brahma Sep 26, 2026
ac11a66
Rail modes: Findings and Judge (#66) (#84)
kiran-brahma Sep 26, 2026
2711d72
The page: Literata, a reading measure and the Status line (#83)
kiran-brahma Sep 26, 2026
c4cd3d4
The mark: blue pencil, underlined at rest (#85)
kiran-brahma Sep 26, 2026
820fead
Report the passive pass at note severity (#53) (#86)
kiran-brahma Sep 26, 2026
71d4da4
Narrow layout: the Rail overlays the prose (#69) (#87)
kiran-brahma Sep 26, 2026
af0b409
The Outline in the left margin on wide screens (#67) (#88)
kiran-brahma Sep 26, 2026
55b0ad8
Margin marks beside the Paragraphs where open Findings begin (#65) (#89)
kiran-brahma Sep 26, 2026
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
31 changes: 25 additions & 6 deletions CONTEXT.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,11 @@ One saved point in a Document's history. An *auto-revision* is taken on a deboun
revision* is marked by the Writer as a milestone and carries a note.
_Avoid_: snapshot, version, save, checkpoint

**Status line**:
The line beneath the prose, at every width, that carries the Document's word count. It is the tool's,
not the Writer's, so it is set in the sans.
_Avoid_: status bar, footer, word counter

**Library**:
Every Document held in this browser.
_Avoid_: workspace, project, vault
Expand Down Expand Up @@ -95,11 +100,18 @@ every other, and no Band is gated on another.
_Avoid_: stage, tier, phase, step, section

**Rail**:
The surface the Writer navigates by Band: the reference strip, the Band control, the selected Band's
Passes with their Findings and accounts, the Judge, and milestones and Revisions. It collapses so the
prose has the width.
The surface beside the prose, in two Rail modes. Findings mode holds the Band control, **All**, the
selected Band's Passes with their Findings and accounts, and the run controls; Judge mode holds the
Judge with milestones and Revisions (ADR 0012). It collapses so the prose has the width. Below 1024px
it overlays the prose instead of sitting beside it, and starts closed on every load.
_Avoid_: sidebar, panel, drawer, nav

**Rail mode**:
One of the Rail's two views — Findings or Judge — switched at its top. The Rail opens on Findings
each session, and the mode is never stored. The queue keys act only in Findings mode; the modifier
step switches to it first.
_Avoid_: tab, view, page, screen

**Target**:
The text a Run is asked about.
_Avoid_: selection, focus, scope
Expand Down Expand Up @@ -130,11 +142,18 @@ The visual rendering of an Anchor. The Current Finding's Highlight is distinguis
_Avoid_: underline, marker

**Callout**:
The popover a click on a Highlight opens beside the prose: the open Findings on that text, with the
queue's verdicts. It does not change the Current Finding, so the Rail stays where the Writer left it
(ADR 0011).
The popover a click on a Highlight or a Margin mark opens beside the prose: the open Findings on that
text, with the queue's verdicts. It does not change the Current Finding, so the Rail stays where the
Writer left it (ADR 0011).
_Avoid_: tooltip, popup, card

**Margin mark**:
The obelus, with a count, in the right-hand margin beside a Paragraph where open Findings begin. A
Finding is counted once, beside the Paragraph it begins in; an Orphaned Finding has none. A click
opens the Callout with those Findings. Kept although the Anchor entry lists *mark* under _Avoid_: that
avoid is about naming an Anchor, and a Margin mark is not one.
_Avoid_: badge, pin, gutter icon, marker

**Orphaned**:
The condition of a Finding whose quoted text can no longer be found, so it points nowhere. A
condition, never a status.
Expand Down
20 changes: 12 additions & 8 deletions docs/migrations.md
Original file line number Diff line number Diff line change
Expand Up @@ -47,20 +47,24 @@ opened, then deploy the behaviour. Rolling the behaviour deploy back to the migr
because the migration deploy's code already understands schema version 7; rolling back past the
migration deploy is the Library outage this rule exists to prevent.

Rolling back a deploy that shipped **no** migration is safe once the service worker is forced to
advance. `public/sw.js` names its cache for the release (bumped on every deploy), so `activate`
deletes the previous release's cache wholesale; it also calls `skipWaiting()` and `clients.claim()` so
the rolled-back shell reaches the Writer immediately, and prunes any asset the current shell no longer
references on every successful navigation. If a migration did ship, a rollback is a Library outage
until forward code returns.
Rolling back a deploy that shipped **no** migration is safe once the Writer's browser re-syncs its
cached shell. `public/sw.js` keeps one cache under a constant name, and the mechanism that does the
work is the navigation-time prune: navigations are network-first, and on every successful online
navigation `syncShellAssets` stores the served `index.html` and deletes every hashed asset it no
longer references, so the next load fetches the rolled-back shell's own assets. That runs in
whichever worker is active, so a rollback needs no worker update; `skipWaiting()` and
`clients.claim()` only make a changed worker take over at once. Until the Writer makes an online
navigation, the cache still holds the shell it last saw. If a migration did ship, a rollback is a
Library outage until forward code returns.

## What enforces it

- `src/storage/obelusDatabase.ts` — the versions and `openObelusDatabase`'s refusal.
- `src/storage/obelusDatabase.test.ts` — an upgrade path from every prior version with existing data
intact, and the newer-database refusal leaving the database untouched.
- `public/sw.js` — a release-keyed cache name, `skipWaiting`/`clients.claim`, precached hashed
assets, and navigation-time pruning, so offline opening and rollback both work.
- `public/sw.js` — navigation-time pruning (`syncShellAssets`), precached hashed assets and
`skipWaiting`/`clients.claim`, so offline opening and rollback both work. The cache name is a
constant; nothing bumps it per deploy.
- The service worker, the CSP header and offline opening are **deploy-time properties**: the
in-memory IndexedDB tests prove the logic, not quota, eviction or a partial migration.

Expand Down
21 changes: 19 additions & 2 deletions harness/constitution.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -51,6 +51,7 @@ let voiceListTransports: FixtureTransport[];
let framedTransports: FixtureTransport[];
let readerTransports: FixtureTransport[];
let auditTransports: FixtureTransport[];
let chunkedAuditTransports: Map<string, FixtureTransport>;
let judgeTransports: FixtureTransport[];

beforeAll(async () => {
Expand Down Expand Up @@ -149,14 +150,20 @@ beforeAll(async () => {

// Story 131: a small character limit forces every fixture Document to chunk,
// so the harness proves the audit splits, synthesizes and reports the count.
chunkedAuditTransports = new Map();
chunkedAuditReport = await runConstitutionHarness({
connection: connection(),
documents: HARNESS_DOCUMENTS,
passes: HARNESS_AUDIT_PASSES,
screeningFrame: true,
characterLimit: 250,
transportFor: (testCase) =>
createFixtureTransport({ respond: () => adversarialAuditResponse(testCase.target) }),
transportFor: (testCase) => {
const transport = createFixtureTransport({
respond: () => adversarialAuditResponse(testCase.target),
});
chunkedAuditTransports.set(`${testCase.documentId}:${testCase.passId}`, transport);
return transport;
},
});

// The Judge is not a Pass, so it gets its own small matrix. It is here because
Expand Down Expand Up @@ -392,6 +399,16 @@ describe("constitution harness", () => {
}
});

it("reports every model call a chunked Audit made, the synthesis included", () => {
// Story 131: `chunks` is how many calls the Run took — one per chunk, plus
// the synthesis over their accounts.
for (const testCase of chunkedAuditReport.cases) {
const transport = chunkedAuditTransports.get(`${testCase.documentId}:${testCase.passId}`);
expect(transport?.requests.length).toBeGreaterThan(2);
expect(testCase.chunks).toBe(transport?.requests.length);
}
});

it("fails a Pass whose prompt drops a constitution clause", async () => {
const stripped: Pass = {
...CLICHE_PASS,
Expand Down
2 changes: 1 addition & 1 deletion harness/constitution.ts
Original file line number Diff line number Diff line change
Expand Up @@ -73,7 +73,7 @@ export interface HarnessCaseResult {
account: ReaderAccount | null;
/** The Audit account an audit Pass returned, if any. */
auditAccount: AuditAccount | null;
/** Story 131: how many chunks the Run was split into; 1 when it fit. */
/** Story 131: how many model calls the Run took; 1 when it fit. */
chunks: number;
rawResponse: string | null;
error: string | null;
Expand Down
4 changes: 3 additions & 1 deletion index.html
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,9 @@
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta name="theme-color" content="#1c1917" />
<meta name="color-scheme" content="light dark" />
<meta name="theme-color" media="(prefers-color-scheme: light)" content="#fafaf9" />
<meta name="theme-color" media="(prefers-color-scheme: dark)" content="#191816" />
<link rel="manifest" href="/manifest.webmanifest" />
<link rel="icon" href="/icon.svg" type="image/svg+xml" />
<title>Obelus</title>
Expand Down
1 change: 1 addition & 0 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,7 @@
"prepare": "node scripts/install-hooks.mjs"
},
"dependencies": {
"@fontsource-variable/literata": "^5.3.0",
"@tiptap/pm": "^3.31.3",
"@tiptap/react": "^3.31.3",
"@tiptap/starter-kit": "^3.31.3",
Expand Down
8 changes: 8 additions & 0 deletions pnpm-lock.yaml

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

10 changes: 6 additions & 4 deletions public/sw.js
Original file line number Diff line number Diff line change
Expand Up @@ -16,10 +16,12 @@
* same-origin request are never intercepted, cached or replayed.
*/

// Keyed to the release: bump this on every deploy. A new name is what lets
// `activate` delete the previous release's cache wholesale, and changing the
// worker's bytes is what makes the browser install the update. The navigation-
// time prune below is the safety net for a release that forgets the bump.
// A constant, not keyed to the release: every deploy shares this one cache.
// What keeps it on the current deploy is the navigation-time prune below
// (`syncShellAssets`), which runs in whichever worker is active on every
// successful online navigation, so a deploy or a rollback needs no worker
// update. `activate` deleting other names only clears a cache this worker no
// longer uses.
const CACHE_NAME = "obelus-shell-v1";
const ASSET_PREFIX = "/assets/";
const SHELL_STATIC_URLS = ["/manifest.webmanifest", "/icon.svg"];
Expand Down
2 changes: 2 additions & 0 deletions scripts/agent-gates.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@ import { checkForbiddenAffordances } from "./gates/affordances.mjs";
import { checkSecurityHeaderParity } from "./gates/headers.mjs";
import { checkImports } from "./gates/imports.mjs";
import { checkLockfileDrift } from "./gates/lockfile.mjs";
import { checkPaletteClasses } from "./gates/palette.mjs";
import { PNPM_LOCK_FILE, readPnpmLock } from "./gates/pnpm-lock.mjs";
import { collectSourceFiles } from "./gates/scan.mjs";
import { checkSilentCatches } from "./gates/silent-catch.mjs";
Expand All @@ -30,6 +31,7 @@ function runChecks() {
],
["no silent catch", checkSilentCatches({ files, repoRoot: REPO_ROOT })],
["no forbidden affordance in the UI source", checkForbiddenAffordances({ files, repoRoot: REPO_ROOT })],
["no palette colour class in the UI source", checkPaletteClasses({ files, repoRoot: REPO_ROOT })],
["no Worker route to a provider", checkNoProviderRoute({ files, repoRoot: REPO_ROOT })],
["the reference Vercel config carries the Worker's Content-Security-Policy", checkSecurityHeaderParity({ repoRoot: REPO_ROOT })],
["lockfile in sync", checkLockfileDrift(packageJson, lock)],
Expand Down
140 changes: 140 additions & 0 deletions scripts/gates/palette.mjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,140 @@
import { readFileSync } from "node:fs";
import ts from "typescript";
import { finding, parseSource, toRepoPath, walk } from "./scan.mjs";

/**
* Build gate: colour by name, never by palette step (spec v1.3, stories
* 201–210).
*
* Every colour the UI draws is a name defined in `src/index.css` — paper, ink,
* muted ink, mark, warning, failure — with a light and a dark value. A palette
* class such as `bg-stone-100` or `text-white` has only one value, so a single
* one left in a component is a patch that stays light in the dark scheme. This
* reads the UI source's string literals, where class names live, and fails the
* build on any palette class or palette variable, whatever its variant or
* opacity. The fix is the name the table in `src/index.css` gives.
*/

const PALETTE_HUES = [
"slate",
"gray",
"zinc",
"neutral",
"stone",
"red",
"orange",
"amber",
"yellow",
"lime",
"green",
"emerald",
"teal",
"cyan",
"sky",
"blue",
"indigo",
"violet",
"purple",
"fuchsia",
"pink",
"rose",
"mauve",
"olive",
"mist",
"taupe",
];

const PALETTE_STEPS = "(?:50|[1-9]00|950)";

/** Every utility that takes a colour. */
const COLOR_UTILITIES = [
"bg",
"text",
"border",
"border-[xytrblse]",
"border-b[se]",
"divide",
"outline",
"ring",
"ring-offset",
"inset-ring",
"shadow",
"inset-shadow",
"drop-shadow",
"text-shadow",
"decoration",
"accent",
"caret",
"fill",
"stroke",
"from",
"via",
"to",
"placeholder",
];

const PALETTE_COLOR = `(?:(?:${PALETTE_HUES.join("|")})-${PALETTE_STEPS}|white|black)`;

/** One class token, once its variants, `!` and opacity are stripped. */
const PALETTE_CLASS = new RegExp(`^-?(?:${COLOR_UTILITIES.join("|")})-${PALETTE_COLOR}$`);

/** A palette variable, as in `bg-(--color-stone-100)` or `var(--color-white)`. */
const PALETTE_VARIABLE = new RegExp(`--color-${PALETTE_COLOR}(?![\\w-])`);

/** UI source: the app's `.ts` and `.tsx` modules, where a class name can be built. */
export function isUiSource(repoPath) {
return (
repoPath.startsWith("src/") &&
(repoPath.endsWith(".tsx") || repoPath.endsWith(".ts")) &&
!repoPath.includes(".test.")
);
}

/** The palette colour a class token names, or null. */
export function paletteClass(token) {
if (PALETTE_VARIABLE.test(token)) return token;
// Variants (`hover:`, `dark:`, `focus-visible:`) end at the last colon.
const utility = token.slice(token.lastIndexOf(":") + 1).replace(/^!|!$/g, "");
const withoutOpacity = utility.replace(/\/[\w.[\]%-]+$/, "");
return PALETTE_CLASS.test(withoutOpacity) ? token : null;
}

/** Palette classes in one file's string literals, with their line. */
export function findPaletteClasses(sourceText, fileName) {
const sourceFile = parseSource(sourceText, fileName);
const findings = [];

walk(sourceFile, (node) => {
if (
!ts.isStringLiteral(node) &&
!ts.isNoSubstitutionTemplateLiteral(node) &&
!ts.isTemplateHead(node) &&
!ts.isTemplateMiddle(node) &&
!ts.isTemplateTail(node)
) {
return;
}
for (const token of node.text.split(/\s+/)) {
const match = paletteClass(token);
if (match === null) continue;
findings.push(
finding(
fileName,
sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile)).line + 1,
`palette colour "${match}": use a colour name from src/index.css, which has a dark value.`,
),
);
}
});

return findings;
}

/** The palette gate over every UI source file. */
export function checkPaletteClasses({ files, repoRoot }) {
return files.flatMap((file) => {
const repoPath = toRepoPath(repoRoot, file);
if (!isUiSource(repoPath)) return [];
return findPaletteClasses(readFileSync(file, "utf8"), repoPath);
});
}
Loading
0