@c4a/context 0.7.14 → 0.7.16

package/docs/guides/knowledge-updates.md

@@ -319,6 +319,12 @@ input without that flag to continue. A preview is not approval and does not make
 a stale revision valid.
 
 Review can approve checked pages while leaving repair pages pending. The HTML
+report shows the current site navigation, candidate changes and expected file
+paths. Unchanged approved pages retain their titles with omitted bodies. Enter
+revision instructions directly in the report; the copied code and following
+instruction lines must be returned together without edits. The CLI binds them to
+the reviewed content and baseline and returns repair commands while leaving
+those pages pending. Changed candidates require a fresh review. The HTML
 review code includes pending positions; managed Review provides the same current
 scope as a JSON template. Send decisions only for pages actually reviewed. Omit
 means a durable exclusion, not repair. Partial approval alone does not build.

package/docs/guides/lark-resources.md

@@ -124,3 +124,41 @@ fixed. Accepted failures remain visible as warnings and unavailable-resource
 notices; they are never represented as downloaded evidence. Review shows
 available previews, references, and warnings so the human or managed policy can
 assess the page with its non-text evidence.
+
+## Image choices for a production task
+
+The work-start report asks once when a task contains more than 30 distinct images
+and has no explicit image policy. The choices are intelligent conversion and
+inclusion (recommended), include all as images with compression, or include none
+with placeholders. Count the whole task, not each capture or writing batch.
+Review reports show the resulting image handling and any fallbacks.
+
+To skip image acquisition while preserving visible source placeholders:
+
+```ts
+captureLark({ source: handbook, resources: { images: "reference-only" } });
+```
+
+To retain static images but exclude GIF files:
+
+```ts
+captureLark({ source: handbook, resources: { gifs: "reference-only" } });
+```
+
+Both fields also accept `bundle`; omitted fields retain normal capture behavior.
+Known GIF metadata avoids downloading; when a source only supplies an opaque
+media token, identification may require downloading the file. Such a GIF is then
+excluded from the snapshot assets and knowledge, rather than decoded or retained.
+Existing evidence is not deleted by changing a policy. Already approved image
+references must be revised through the normal Review flow to change their content.
+
+Inclusion does not mean lossless original-byte delivery. The package optimizer
+preserves animations without decoding every frame or silently flattening them.
+Codec failures and images that cannot fit delivery budgets become visible output
+placeholders with a build warning; approved source bytes remain unchanged.
+Do not rewrite approved prose to repair a codec error or disable pixel safety
+limits. The reading meaning of an image is handled in writing and Review.
+
+Source document links can be retained for viewing under the reader's permissions.
+Temporary signed media links are not durable image hosting. Do not embed access
+tokens in generated pages or claim that excluded images have been interpreted.

package/docs/guides/package-outputs.md

@@ -93,8 +93,14 @@ The website uses a full-width VitePress theme with system fonts, compact navigat
 a wide reading area and a smaller article outline. It starts in
 light mode regardless of the operating system; an explicit reader choice is
 remembered in browser storage. Search runs locally, without a search service.
-Mermaid renders in the browser with a restrained theme; invalid diagrams retain
-their source instead of blocking publication. Code samples and raw HTML are
+Mermaid renders in the browser using the website theme, with fit, original-size,
+zoom, full-screen and source controls. Controls appear on hover or keyboard focus
+(and remain visible on touch devices). Layout and source/copy actions are on the
+left, sizing actions on the right. Source view replaces the diagram. Flowcharts default to ELK and can switch to Dagre without changing the article. Offline Review reports use the same
+viewer and include its resources only when a candidate contains Mermaid.
+Article provenance initially shows ten sources; Show more reveals the full list.
+Invalid diagrams and diagrams with embedded image/HTML resources retain their
+source with a rendering notice instead of blocking publication. Code samples and raw HTML are
 displayed as content, not executed as Vue components or scripts.
 
 The accepted `src/knowledge-map.yaml` controls sidebar organization. Entries
@@ -501,3 +507,31 @@ result instead of guessing a hostname. No new workspace configuration is needed.
 The address is an access hint, not proof of publication or content freshness.
 Query Skills use it only to append related links in the final summary, with no
 network probes or version checks. Packages without the map work as before.
+
+### Shared color theme
+
+Website builds create `src/site/theme.json` with the current default light and
+ dark palettes if the file is missing. Edit this optional JSON file to customize
+all websites and offline Review reports in the workspace. It is configuration,
+not a generated HTML file: builds never overwrite existing values. Deleting it
+restores built-in defaults; Review does not need the file or an existing website
+build. The next website build recreates it.
+
+Each `light`/`dark` object supports `brand`, `accent`, `background`, `surface`,
+`text`, `mutedText`, and `border`. Values are hexadecimal CSS colors (`#RGB`,
+`#RRGGBB`, or `#RRGGBBAA`). Partial objects inherit missing default colors. Invalid
+JSON or colors produce a configuration error identifying the optional file.
+
+A package may override these colors through `kbPackage({ site: { theme: {
+light: { brand: "#6750a4" }, dark: { brand: "#d0bcff" }
+} } })`. Precedence is built-in defaults, workspace file, then `site.theme`.
+A Review with one website package uses that package's overrides. With multiple
+website packages it uses the shared workspace theme, without selecting an
+arbitrary package. New/Modify/approve/reject status colors remain independent.
+
+The compiler projects tokens into VitePress and standalone Review CSS. Mermaid
+reads the same resolved colors. Changes to the theme invalidate website build
+receipts. Arbitrary extension CSS is not copied into Review; custom components
+can consume `--context-brand`, `--context-accent`, `--context-background`,
+`--context-surface`, `--context-text`, `--context-muted-text`, and
+`--context-border` rather than hard-coding colors.

package/index.d.ts

@@ -1,3 +1,4 @@
+export { siteThemeSchema, DEFAULT_SITE_THEME, type SiteTheme, type SiteThemeColors } from "./siteTheme.js";
 import { type PackageSiteDefinition } from "./packageSite.js";
 export { packageSiteSchema, type PackageSiteDefinition } from "./packageSite.js";
 import type { PackageNavigationDefinition, PackageSelectDefinition } from "./contracts.js";

package/index.js

@@ -10888,6 +10888,22 @@ var coerce = {
   date: (arg) => ZodDate.create({ ...arg, coerce: true })
 };
 var NEVER = INVALID;
+// src/siteTheme.ts
+var color = exports_external.string().regex(/^#(?:[\da-f]{3}|[\da-f]{6}|[\da-f]{8})$/iu, "Use a hexadecimal CSS color (#RGB, #RRGGBB or #RRGGBBAA)");
+var siteThemeColorsSchema = exports_external.object({
+  brand: color.optional(),
+  accent: color.optional(),
+  background: color.optional(),
+  surface: color.optional(),
+  text: color.optional(),
+  mutedText: color.optional(),
+  border: color.optional()
+}).strict();
+var siteThemeSchema = exports_external.object({ light: siteThemeColorsSchema.optional(), dark: siteThemeColorsSchema.optional() }).strict();
+var DEFAULT_SITE_THEME = {
+  light: { brand: "#2563eb", accent: "#00bec8", background: "#ffffff", surface: "#f8f9fc", text: "#161e2e", mutedText: "#646b7c", border: "#e7e9ef" },
+  dark: { brand: "#8eb7ff", accent: "#b3cfff", background: "#171b24", surface: "#1b1d24", text: "#e2e4ed", mutedText: "#a1a6b7", border: "#303440" }
+};
 // src/packageSite.ts
 var siteHrefSchema = exports_external.string().trim().min(1).refine((value) => /^(?:https?:\/\/|mailto:|\/(?!\/)|#)/u.test(value), "Use an https URL, mailto URL, root-relative path, or page anchor");
 var packageSiteHomeActionSchema = exports_external.object({
@@ -10913,6 +10929,7 @@ var packageSiteHomeSchema = exports_external.object({
   resources: exports_external.array(packageSiteHomeResourceSchema).optional()
 }).strict();
 var packageSiteSchema = exports_external.object({
+  theme: siteThemeSchema.optional(),
   title: exports_external.string().trim().min(1).optional(),
   description: exports_external.string().optional(),
   lang: exports_external.string().min(1).default("en-US"),
@@ -31425,6 +31442,12 @@ var captureFile = (definition) => {
 var captureLark = (definition) => {
   const sourceDefinition = bindSourceType(definition.source, "lark", "captureLark source");
   const sourceId = getSourceName(sourceDefinition);
+  for (const key of ["images", "gifs"]) {
+    const value = definition.resources?.[key];
+    if (value !== undefined && value !== "bundle" && value !== "reference-only") {
+      throw new TypeError(`captureLark resources.${key} must be bundle or reference-only`);
+    }
+  }
   const maxBytesPerResource = definition.resources?.maxBytesPerResource ?? 20 * 1024 * 1024;
   const maxTotalBytes = definition.resources?.maxTotalBytes ?? 200 * 1024 * 1024;
   if (!Number.isSafeInteger(maxBytesPerResource) || maxBytesPerResource < 1) {
@@ -31443,6 +31466,8 @@ var captureLark = (definition) => {
     writes: [sourceSnapshotResource(sourceDefinition, "lark")],
     source: sourceDefinition,
     resources: {
+      ...definition.resources?.images === undefined ? {} : { images: definition.resources.images },
+      ...definition.resources?.gifs === undefined ? {} : { gifs: definition.resources.gifs },
       videos: definition.resources?.videos ?? "reference-only",
       maxBytesPerResource,
       maxTotalBytes
@@ -32405,6 +32430,7 @@ export {
   startIndexerMainRun,
   sourceUpdateSemanticInputSchema,
   source,
+  siteThemeSchema,
   sessionChangesSchema,
   sessionChangeSchema,
   sameIndexerParserExecutionPlan,
@@ -32979,6 +33005,7 @@ export {
   DOCUMENT_SECTION_CONTENT_MODES,
   DOCUMENT_EVIDENCE_SECTION_VALIDATION_STAGES,
   DOCUMENT_COMPILE_ACTION_SCHEMA_VERSION,
+  DEFAULT_SITE_THEME,
   DEFAULT_REPO_SOURCES_REGISTRY_PATH,
   DEFAULT_PACKAGE_NAVIGATION,
   DEFAULT_LARK_SOURCES_REGISTRY_PATH,

package/indexerArtifactPolicy.d.ts

@@ -10,11 +10,11 @@ export declare const indexerArtifactPolicyEligibilitySchema: z.ZodObject<{
         path: z.ZodString;
         value: z.ZodType<IndexerJson, z.ZodTypeDef, IndexerJson>;
     }, "strict", z.ZodTypeAny, {
-        path: string;
         value: IndexerJson;
-    }, {
         path: string;
+    }, {
         value: IndexerJson;
+        path: string;
     }>, "many">;
     provider_supported_variants: z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">;
     eligible_variants: z.ZodArray<z.ZodObject<{
@@ -71,8 +71,8 @@ export declare const indexerArtifactPolicyEligibilitySchema: z.ZodObject<{
     profile_id: string;
     profile_contract_digest: string;
     canonical_facts: {
-        path: string;
         value: IndexerJson;
+        path: string;
     }[];
     provider_supported_variants: string[];
     eligible_variants: {
@@ -94,8 +94,8 @@ export declare const indexerArtifactPolicyEligibilitySchema: z.ZodObject<{
     profile_id: string;
     profile_contract_digest: string;
     canonical_facts: {
-        path: string;
         value: IndexerJson;
+        path: string;
     }[];
     provider_supported_variants: string[];
     eligible_variants: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@c4a/context",
-  "version": "0.7.14",
+  "version": "0.7.16",
   "type": "module",
   "description": "Declarative SDK for Context knowledge sources, workflows, review, and package outputs",
   "license": "MIT",

package/packageSite.d.ts

@@ -1,6 +1,96 @@
 import { z } from "zod";
 /** Static website in a sibling dist/<name-without-trailing-kb>-site directory. */
 export declare const packageSiteSchema: z.ZodObject<{
+    theme: z.ZodOptional<z.ZodObject<{
+        light: z.ZodOptional<z.ZodObject<{
+            brand: z.ZodOptional<z.ZodString>;
+            accent: z.ZodOptional<z.ZodString>;
+            background: z.ZodOptional<z.ZodString>;
+            surface: z.ZodOptional<z.ZodString>;
+            text: z.ZodOptional<z.ZodString>;
+            mutedText: z.ZodOptional<z.ZodString>;
+            border: z.ZodOptional<z.ZodString>;
+        }, "strict", z.ZodTypeAny, {
+            brand?: string | undefined;
+            accent?: string | undefined;
+            background?: string | undefined;
+            surface?: string | undefined;
+            text?: string | undefined;
+            mutedText?: string | undefined;
+            border?: string | undefined;
+        }, {
+            brand?: string | undefined;
+            accent?: string | undefined;
+            background?: string | undefined;
+            surface?: string | undefined;
+            text?: string | undefined;
+            mutedText?: string | undefined;
+            border?: string | undefined;
+        }>>;
+        dark: z.ZodOptional<z.ZodObject<{
+            brand: z.ZodOptional<z.ZodString>;
+            accent: z.ZodOptional<z.ZodString>;
+            background: z.ZodOptional<z.ZodString>;
+            surface: z.ZodOptional<z.ZodString>;
+            text: z.ZodOptional<z.ZodString>;
+            mutedText: z.ZodOptional<z.ZodString>;
+            border: z.ZodOptional<z.ZodString>;
+        }, "strict", z.ZodTypeAny, {
+            brand?: string | undefined;
+            accent?: string | undefined;
+            background?: string | undefined;
+            surface?: string | undefined;
+            text?: string | undefined;
+            mutedText?: string | undefined;
+            border?: string | undefined;
+        }, {
+            brand?: string | undefined;
+            accent?: string | undefined;
+            background?: string | undefined;
+            surface?: string | undefined;
+            text?: string | undefined;
+            mutedText?: string | undefined;
+            border?: string | undefined;
+        }>>;
+    }, "strict", z.ZodTypeAny, {
+        light?: {
+            brand?: string | undefined;
+            accent?: string | undefined;
+            background?: string | undefined;
+            surface?: string | undefined;
+            text?: string | undefined;
+            mutedText?: string | undefined;
+            border?: string | undefined;
+        } | undefined;
+        dark?: {
+            brand?: string | undefined;
+            accent?: string | undefined;
+            background?: string | undefined;
+            surface?: string | undefined;
+            text?: string | undefined;
+            mutedText?: string | undefined;
+            border?: string | undefined;
+        } | undefined;
+    }, {
+        light?: {
+            brand?: string | undefined;
+            accent?: string | undefined;
+            background?: string | undefined;
+            surface?: string | undefined;
+            text?: string | undefined;
+            mutedText?: string | undefined;
+            border?: string | undefined;
+        } | undefined;
+        dark?: {
+            brand?: string | undefined;
+            accent?: string | undefined;
+            background?: string | undefined;
+            surface?: string | undefined;
+            text?: string | undefined;
+            mutedText?: string | undefined;
+            border?: string | undefined;
+        } | undefined;
+    }>>;
     title: z.ZodOptional<z.ZodString>;
     description: z.ZodOptional<z.ZodString>;
     lang: z.ZodDefault<z.ZodString>;
@@ -140,6 +230,26 @@ export declare const packageSiteSchema: z.ZodObject<{
 }, "strict", z.ZodTypeAny, {
     lang: string;
     base: string;
+    theme?: {
+        light?: {
+            brand?: string | undefined;
+            accent?: string | undefined;
+            background?: string | undefined;
+            surface?: string | undefined;
+            text?: string | undefined;
+            mutedText?: string | undefined;
+            border?: string | undefined;
+        } | undefined;
+        dark?: {
+            brand?: string | undefined;
+            accent?: string | undefined;
+            background?: string | undefined;
+            surface?: string | undefined;
+            text?: string | undefined;
+            mutedText?: string | undefined;
+            border?: string | undefined;
+        } | undefined;
+    } | undefined;
     title?: string | undefined;
     description?: string | undefined;
     home?: {
@@ -172,6 +282,26 @@ export declare const packageSiteSchema: z.ZodObject<{
         pages?: Record<string, string> | undefined;
     } | undefined;
 }, {
+    theme?: {
+        light?: {
+            brand?: string | undefined;
+            accent?: string | undefined;
+            background?: string | undefined;
+            surface?: string | undefined;
+            text?: string | undefined;
+            mutedText?: string | undefined;
+            border?: string | undefined;
+        } | undefined;
+        dark?: {
+            brand?: string | undefined;
+            accent?: string | undefined;
+            background?: string | undefined;
+            surface?: string | undefined;
+            text?: string | undefined;
+            mutedText?: string | undefined;
+            border?: string | undefined;
+        } | undefined;
+    } | undefined;
     title?: string | undefined;
     description?: string | undefined;
     lang?: string | undefined;
@@ -210,6 +340,26 @@ export type PackageSiteDefinition = z.input<typeof packageSiteSchema>;
 export declare function normalizePackageSite(value: PackageSiteDefinition | undefined): {
     lang: string;
     base: string;
+    theme?: {
+        light?: {
+            brand?: string | undefined;
+            accent?: string | undefined;
+            background?: string | undefined;
+            surface?: string | undefined;
+            text?: string | undefined;
+            mutedText?: string | undefined;
+            border?: string | undefined;
+        } | undefined;
+        dark?: {
+            brand?: string | undefined;
+            accent?: string | undefined;
+            background?: string | undefined;
+            surface?: string | undefined;
+            text?: string | undefined;
+            mutedText?: string | undefined;
+            border?: string | undefined;
+        } | undefined;
+    } | undefined;
     title?: string | undefined;
     description?: string | undefined;
     home?: {

package/phases.d.ts

@@ -50,6 +50,8 @@ export type CaptureLarkPhaseDefinition = {
     writes: readonly PhaseResourceReference[];
     source: LarkSourceDefinition | LarkSourceReference;
     resources: {
+        images?: "reference-only" | "bundle";
+        gifs?: "reference-only" | "bundle";
         videos: "reference-only" | "bundle";
         maxBytesPerResource: number;
         maxTotalBytes: number;
@@ -76,6 +78,8 @@ export declare const captureFile: (definition: {
 export declare const captureLark: (definition: {
     source: LarkSourceDefinition | LarkSourceReference;
     resources?: {
+        images?: "reference-only" | "bundle";
+        gifs?: "reference-only" | "bundle";
         videos?: "reference-only" | "bundle";
         maxBytesPerResource?: number;
         maxTotalBytes?: number;

package/siteTheme.d.ts

@@ -0,0 +1,122 @@
+import { z } from "zod";
+export declare const siteThemeColorsSchema: z.ZodObject<{
+    brand: z.ZodOptional<z.ZodString>;
+    accent: z.ZodOptional<z.ZodString>;
+    background: z.ZodOptional<z.ZodString>;
+    surface: z.ZodOptional<z.ZodString>;
+    text: z.ZodOptional<z.ZodString>;
+    mutedText: z.ZodOptional<z.ZodString>;
+    border: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    brand?: string | undefined;
+    accent?: string | undefined;
+    background?: string | undefined;
+    surface?: string | undefined;
+    text?: string | undefined;
+    mutedText?: string | undefined;
+    border?: string | undefined;
+}, {
+    brand?: string | undefined;
+    accent?: string | undefined;
+    background?: string | undefined;
+    surface?: string | undefined;
+    text?: string | undefined;
+    mutedText?: string | undefined;
+    border?: string | undefined;
+}>;
+export declare const siteThemeSchema: z.ZodObject<{
+    light: z.ZodOptional<z.ZodObject<{
+        brand: z.ZodOptional<z.ZodString>;
+        accent: z.ZodOptional<z.ZodString>;
+        background: z.ZodOptional<z.ZodString>;
+        surface: z.ZodOptional<z.ZodString>;
+        text: z.ZodOptional<z.ZodString>;
+        mutedText: z.ZodOptional<z.ZodString>;
+        border: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        brand?: string | undefined;
+        accent?: string | undefined;
+        background?: string | undefined;
+        surface?: string | undefined;
+        text?: string | undefined;
+        mutedText?: string | undefined;
+        border?: string | undefined;
+    }, {
+        brand?: string | undefined;
+        accent?: string | undefined;
+        background?: string | undefined;
+        surface?: string | undefined;
+        text?: string | undefined;
+        mutedText?: string | undefined;
+        border?: string | undefined;
+    }>>;
+    dark: z.ZodOptional<z.ZodObject<{
+        brand: z.ZodOptional<z.ZodString>;
+        accent: z.ZodOptional<z.ZodString>;
+        background: z.ZodOptional<z.ZodString>;
+        surface: z.ZodOptional<z.ZodString>;
+        text: z.ZodOptional<z.ZodString>;
+        mutedText: z.ZodOptional<z.ZodString>;
+        border: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        brand?: string | undefined;
+        accent?: string | undefined;
+        background?: string | undefined;
+        surface?: string | undefined;
+        text?: string | undefined;
+        mutedText?: string | undefined;
+        border?: string | undefined;
+    }, {
+        brand?: string | undefined;
+        accent?: string | undefined;
+        background?: string | undefined;
+        surface?: string | undefined;
+        text?: string | undefined;
+        mutedText?: string | undefined;
+        border?: string | undefined;
+    }>>;
+}, "strict", z.ZodTypeAny, {
+    light?: {
+        brand?: string | undefined;
+        accent?: string | undefined;
+        background?: string | undefined;
+        surface?: string | undefined;
+        text?: string | undefined;
+        mutedText?: string | undefined;
+        border?: string | undefined;
+    } | undefined;
+    dark?: {
+        brand?: string | undefined;
+        accent?: string | undefined;
+        background?: string | undefined;
+        surface?: string | undefined;
+        text?: string | undefined;
+        mutedText?: string | undefined;
+        border?: string | undefined;
+    } | undefined;
+}, {
+    light?: {
+        brand?: string | undefined;
+        accent?: string | undefined;
+        background?: string | undefined;
+        surface?: string | undefined;
+        text?: string | undefined;
+        mutedText?: string | undefined;
+        border?: string | undefined;
+    } | undefined;
+    dark?: {
+        brand?: string | undefined;
+        accent?: string | undefined;
+        background?: string | undefined;
+        surface?: string | undefined;
+        text?: string | undefined;
+        mutedText?: string | undefined;
+        border?: string | undefined;
+    } | undefined;
+}>;
+export type SiteTheme = z.infer<typeof siteThemeSchema>;
+export type SiteThemeColors = Required<z.infer<typeof siteThemeColorsSchema>>;
+export declare const DEFAULT_SITE_THEME: {
+    light: SiteThemeColors;
+    dark: SiteThemeColors;
+};