One drawing, several projections

KJDocument is the source of truth. The canvas, property panel, selection overlay, SVG preview and exported file are projections of that document; none of them replaces it. A document owns its units, resources, model and paper spaces, layouts and drawing objects.

Saving KJD preserves KJDraw's native document data. DXF is an interchange projection with an explicitly published compatibility boundary. Reopen the produced file when a workflow needs evidence that serialization did not change the drawing.

Stable object identity

Every drawing object has a stable ID. Application code and agent workflows should keep and query IDs instead of locating an object again from approximate coordinates or display order. A revision identifies the document state against which a read or proposal was prepared.

Copyconst created = await sdk.executeCommand<{ id: string }>('CREATE', {
  type: 'CIRCLE',
  payload: { center: [20, 20, 0], radius: 5 },
})

const circleId = created.result.id
console.log(document.revision, circleId)

Commands and transactions

Commands are the public mutation boundary. They validate arguments, change the document and return a receipt. Related low-level changes can be grouped into one transaction so they commit or fail together. The editor, plugins and approved automation use the same command path, which keeps undo, redo and document events consistent.

Do not mutate a serialized KJD object or a renderer display list and expect the active document to update. Use a command or a document transaction.

Files and adapters

File adapters translate between a KJDocument and a bounded format. KJD is native, KJP packages a project, and DXF supports the subset documented in the compatibility contract. Storage, authentication and upload policy remain host responsibilities; opening a file does not silently send it to a service.

Agent proposals are not implicit edits

An agent session reads a bounded drawing context and returns a proposal. A trusted host previews and approves the operation before applying it. The proposal carries the revision it was prepared against so a stale operation can be rejected instead of being applied to a different drawing state.

Copyread bounded context -> propose -> preview -> approve -> apply -> save -> reopen

Use the direct command API for deterministic application code. Use proposal tools when a person or host policy must review a model-produced change.

Knowledge packs compile domain facts

A knowledge pack is versioned declarative engineering knowledge. It combines an ontology and bounded templates or rules with a semantic intent, then compiles them into deterministic command arguments. It is not a dump of a private drawing and it does not grant a model access to source files.

Continue with Commands and transactions for application edits, Agent workflows for reviewed model changes, and Knowledge packs for domain compilers.